このドキュメントでは、グラフのデータを Google Chart API に送信する方法について説明します。
目次
概要
ほぼすべてのグラフのデータは、chd パラメータを使用して送信されます。データは次のいずれかの形式で送信する必要があります。
- 基本テキスト形式は、基本的に 0 ～ 100 の単純な浮動小数点数です。この形式は、手動で簡単に読み書きできます。
- 自動スケーリングのテキスト形式では、データに合わせてグラフがスケーリングされます。
- カスタム スケーリングのテキスト形式は基本的なテキスト形式に似ていますが、2 つ目の URL パラメータを使用してカスタム範囲を指定できます。
- シンプルなエンコード形式では、1 文字の英数字でエンコードされた 0 ～ 61 の整数値を指定できます。このエンコードにより、いずれかのデータ形式の中で最も短いデータ文字列になります（値が 9 より大きい場合）。
- 拡張エンコード形式では、2 文字の英数字でエンコードされた 0 ～ 4095 の整数値を指定できます。拡張エンコードは、大量のデータとデータ範囲があるグラフに最適です。
データ値は、使用される形式に合わせてスケーリングされます。グラフに合わせてデータがどのように操作されるかについては、データのスケーリングと軸のスケーリングをご覧ください。
Google では、データをシンプルなエンコード形式または拡張エンコード形式にエンコードするための JavaScript スニペットを提供しています。別の方法として、Google Chart のグループ メンバー何人かがフォーマットに役立つ他のライブラリを提供しており、アーカイブを検索して見つけてもらいます。
基本テキスト形式
基本的なテキスト形式のデータでは、0 ～ 100 の浮動小数点値を数値として指定できます。0 未満の値は欠損値としてマークされ、100 を超える値は 100 で切り捨てられます。基本的なテキスト形式の利点は、URL で値を読みやすく、理解しやすく、デフォルトの軸ラベルでデータ値が正確に表示されることです。ただし、テキスト形式（単純な形式かカスタム パラメータ付きかにかかわらず）は、すべての形式の中で最も長いデータ文字列になります。
指定されたテキスト形式の範囲外の値がデータに含まれている場合は、データの最大値に対するパーセンテージに変換することでデータをスケーリングできます。または、カスタム スケーリングのテキスト形式を使用してスケーリングを処理することもできます。
構文:
chd=t:val,val,val|val,val,val...
- <data>
- 各系列は 1 つ以上のカンマ区切り値です。複数のシリーズはパイプ文字（
|）で区切ります。値は 0 ～ 100 の浮動小数点数です。0 未満の値またはアンダースコア（_）は null 値とみなされます。100 を超える値は 100 で切り捨てられます。
例:
| 5 つの値を持つテーブル。アンダースコアは null 値とみなされ、-30 は最小値を下回るため破棄され、200 値は 100 で切り捨てられます。 |  chd=t:_,30,-30,50,80,200 |
自動スケーリングを使用したテキスト形式
一部のグラフは、データに合わせて自動的にスケーリングされるように構成できます。グラフは、最大値がグラフの上部、最小値（すべての値が 0 より大きい場合はゼロ）が一番下になるようにスケーリングされます。
グラフに表示されるマーカー値には、スケーリングされた値ではなく、実際の値が表示されます。
この機能はテキスト形式の値でのみ機能します。また、すべての種類のグラフで利用できるわけではありません。グラフの種類を試して、サポートされているかどうかを確認してください。
構文
cht=t:val,val,val... chds=a
例:
円グラフでは、0 未満の値は使用しないでください。 |
 chd=t:-5,30,-30,50,80,200 |
カスタム スケーリングのテキスト形式
カスタム スケーリングのテキスト形式では、グラフのカスタム範囲を指定できるスケーリング パラメータと組み合わせて、任意の正または負の浮動小数点数を指定できます。このグラフは、データを特定の範囲に制限したくない場合や、グラフ内に収めるためにデータを手動でスケーリングしたくない場合に役立ちます。この形式では、必要に応じて基準線が調整されます。データの形式は基本的なテキスト形式と同じです。
自動スケーリングの場合は、chds=a を指定します。
テキスト形式（単純な形式かカスタム パラメータ付きかにかかわらず）は、すべての形式の中で最も長いデータ文字列になります。
構文:
カスタム スケーリングのテキスト形式には、次の 2 つのパラメータが必要です。
chd=t:val,val,val|val,val,val chds=<series_1_min>,<series_1_max>,...,<series_n_min>,<series_n_max>
- chd=t:<data>
- 書式なしデータ形式と同じです。系列ごとに 1 つ以上のカンマ区切り値、複数の系列はパイプ文字（
|）で区切られます。各系列で許可される値の範囲はchdsパラメータで指定されます。 - コード
- 各データ系列の 1 つ以上の最小値と最大値をカンマで区切ったセット。最大値と最小値の両方を指定する必要があります。データ系列数よりも少ないペア数を指定した場合、最後のペアが残りのすべてのデータ系列に適用されます。軸の範囲は変更されないことに注意してください。軸範囲を変更するには、
chxrパラメータを設定する必要があります。 有効な値の範囲は (+/-)9.999e(+/-)199 です。値は標準表記または E 表記で指定できます。- <series_1_min>
- 最初の系列の最小許容値。これより小さい値は欠損値としてマークされます。
- <series_1_maxseries_1_max>
- 最初の系列の最大許容値。値が大きいほど、この値に切り捨てられます。
例:
-80 ～ 140 のスケール（最小/最大）の棒グラフ。30、-60、50、140、80 の値はスケールの範囲に入るため、切り捨てられません。基準線は 80÷(140 + 80) = y 軸を上向きに 0.36 ずれた分、自動的に調整されます。 また、 |
|
シンプル エンコード形式
シンプルなエンコード形式で 1 文字の英数字でエンコードされた 0 ～ 61 の整数値を指定できます。これにより、すべてのデータ形式の中で最も短いデータ文字列 URL になります。ただし、データ軸に沿って 100 ピクセルを超える折れ線グラフまたは棒グラフの場合は、別の形式を使用することをおすすめします。これは、サポートされるデータ値が 62 個しかない場合、データの粒度が表示の粒度よりもはるかに大きくなり、値がほとんどずれるだけであるためです（大きなグラフでは見られない）。
chds パラメータを単純なエンコードで使用しても、グラフ上のデータ要素のサイズは影響を受けませんが、データポイント マーカーの値には影響します。
構文:
chd=s:
<series_1>
,...,
<series_n>
- <series_1>
- 文字列。各文字は単一のデータポイントであり、シリーズはカンマで区切られます。シリーズ内の個々の値は区切りません。サポートされているデータ文字とそれに対応する値は次のとおりです。
A—Z（A= 0、B= 1、以下同様）、Z= 25a—z（a= 26、b= 27、以下同様、z= 51）0(zero)—9（0= 52、9= 61）- アンダースコア文字（
_）は欠損値を示します
次のツールを使用して単一の値をエンコードするか、JavaScript コードを使用して URL 文字列全体の調整とエンコードを行います。
例:
テキスト エンコードされた文字列 chd=t:1,19,27,53,61,-1|12,39,57,45,51,27 と同等 |
<title="chs=320x200&cht=bvs&chd=s:btb19_,mn5tzb&chco=ffcc33,ffe9a4&chxr=0,0,61,5&chxt=y" alt="シンプルなエンコーディングによる積み上げ棒グラフ。chd=s:BTb19_,Mn5tzb |
拡張エンコード形式
拡張エンコード形式では、2 文字の英数字でエンコードされた 0 ～ 4095 の整数値を指定できます。単純なエンコードとは構文が若干異なります。
なお、chds パラメータを単純なエンコードで使用しても、グラフ上のデータ要素のサイズは影響を受けませんが、データポイント マーカーの値には影響します。
構文:
chd=e:
<series_1>
,...,
<series_n>
- <series_1>
- 2 文字が 1 つのデータポイントであり、シリーズがカンマで区切られる文字列。系列内の個々の値は区切られません。サポートされているエンコード文字は次のとおりです。
A—Za—z0—9- 期間（
.） - ハイフン（
-） - 欠損値は二重アンダースコア（
__）で示されます。
エンコードされた値の簡単な説明を次に示します。
AA= 0、AB= 1（以下同様）AZ= 25Aa= 26、Ab= 27、以下と同様にAz= 51A0= 52、A1= 53、以下と同様にA9= 61A-= 62、A.= 63BA= 64、BB= 65、以下と同様にBZ= 89Ba= 90、Bb= 91（以下同様）Bz= 115B0= 116、B1= 117、以下と同様にB9= 125B-= 126、B.= 1279A= 3,904、9B= 3,905、以下と同様に9Z= 3,9299a= 3,930、9b= 3,931、以下と同様に9z= 3,95590= 3,956、91= 3,957、以下と同様に99= 3,9659-= 3966、9.= 3967-A= 3,968、-B= 3,969、以下と同様に-Z= 3,993-a= 3,994、-b= 3,995、以下と同様に-z= 4,019-0= 4,020、-1= 4,021、以下と同様に-9= 4,029--= 4030、-.= 4031.A= 4,032、.B= 4,033、以下と同様に.Z= 4,057.a= 4,058、.b= 4,059、以下と同様に.z= 4,083.0= 4,084、.1= 4,085、以下と同様に.9= 4,093.-= 4094、..= 4095
次のツールを使用して単一の値をエンコードするか、JavaScript コードを使用して URL 文字列全体の調整とエンコードを行います。
例:
テキスト エンコードされた文字列 chd=t:90,1000,2700,3500|3968,-1,1100,250 と同等 |
 chd=e:BaPoqM2s,-A__RMD6 |
データのスケーリングと軸のスケーリング
データは、明示的に（カスタム スケーリングのテキスト形式を使用する場合）、または暗黙的に（他のすべてのタイプの場合）グラフに合わせてスケーリングされます。つまり、各グラフは、提供するデータの実際の範囲ではなく、使用可能な形式の範囲に合わせてスケーリングされます。
フォーマットで許容される値の範囲すべてが含まれるようにデータをスケーリングすると、違いを明確にできます。データをスケーリングするには、使用する形式に合わせてデータをスケーリングするか、データ範囲を明示的に指定します（カスタム スケーリングのテキスト形式を使用します）。
軸ラベルの値は完全に独立したスケールで計算され、データ値とは関係ありませんが、デフォルトの範囲である 0 ～ 100 を使用します。ただし、この範囲は変更できます。
このセクションでは、この両方の問題について説明します。
データは形式範囲に合わせてスケーリングされます [円とベンを除くすべてのグラフ]
形式が異なれば、サポートされる値の範囲も異なります。データは指定した形式の範囲に合わせてスケーリングされます。指定した形式でサポートされている最大値がその軸の上部にレンダリングされ、形式の最小値が一番下にレンダリングされます。次の例では、同じ値（100）を基本テキスト形式（範囲 0 ～ 100）、カスタム スケーリングを適用したテキスト（0 ～ 200 のカスタム範囲）、拡張エンコード形式（範囲 0 ～ 4095）を使用した例を示しています。
| 基本テキスト形式 | カスタム スケーリングのテキスト形式 | 拡張エンコード形式 |
|---|---|---|
 |
 |
 |
値: 100（ 形式範囲: 0 ～ 100 100 は、スケールが 100/100 でレンダリングされます。 |
値 100（ 形式範囲: 0 ～ 200 100 は 100/200 のスケールでレンダリングされます。 |
値: 100（ 形式範囲: 0 ～ 4095 100 は、尺度の高い 100/4095 としてレンダリングされます。 |
スケーリングしたテキスト形式を使用すると、グラフに合わせてデータを簡単にスケーリングできます。より複雑な方法は、サポートする形式の範囲内に収まるようにデータを手動でスケーリングすることです。
円グラフとベングラフ: 円グラフとベングラフでは、すべての値が互いに相対的であり、グラフの合計尺度に対する比率ではありません。
 |
 |
chd=e:BkDIEs |
chd=t:100,200,300 |
軸ラベルの範囲は個別に計算されます（棒、折れ線、レーダー、散布図、ローソク足）
軸の値を表示するには、chxt パラメータを使用します。ただし、軸ラベルはグラフのデータを反映するように計算されるのではなく、API によって個別に計算されるか、ユーザーが明示的に指定します。
軸のデフォルトの範囲は 0 ～ 100 で、データ値やデータ スケーリングに関係ありません。たとえば、拡張エンコード（範囲 0 ～ 4095）を使用するグラフでデフォルトの軸ラベルを使用して y 軸を表示する場合、以下で説明するように明示的に変更しない限り、y 軸のラベルは 0 ～ 100 の値のままとなります。次の例は、データ値が 100 の拡張エンコード棒グラフにデフォルトの y 軸ラベルを示しています。
chd=e:Bk（chd=t:100 に相当）
ただし、chxr パラメータを使用すると、軸の範囲を指定できます。軸の値に実際のデータ値を反映させるには、形式の範囲と一致する軸の最小値と最大値を指定する必要があります。基本テキスト形式のスケールはすでに 0 ～ 100 であるため、基本テキスト形式（カスタム スケーリングなし）を使用している場合、軸の値はデフォルトでデータ値と一致します。いくつかの例を使って説明します次に、同じデータ（15、26、51、61）で、形式と軸のスケールが異なる 3 つのグラフを示します。
| シンプルなエンコード、軸スケーリングなし | シンプル エンコード、スケーリングされた軸 | 基本テキスト、軸スケーリングなし |
|---|---|---|
 |
 |
 |
単純なエンコード値の範囲: 0 ～ 61 デフォルトの軸の範囲（0 ～ 100） エンコード範囲はラベルの軸の範囲よりも小さいため、棒は軸ラベルの実際の値に対応していません。ただし、棒は互いに適切な比率になっています。 |
単純なエンコード値の範囲: 0 ～ 61 軸の範囲が明示的に 0 ～ 61 に設定されている エンコード範囲と軸範囲は同じであるため、棒は軸上の正しい値に対応しています。 |
基本的なテキスト形式の値の範囲: 0 ～ 100 デフォルトの軸の範囲（0 ～ 100） エンコードの範囲と軸の範囲も同じであるため、デフォルトで正確なデータ値が軸に表示されます。 テキスト形式の範囲は単純なエンコード形式の範囲（100 単位と 61 単位）よりも大きいため、ここでは他のグラフよりも棒が小さくなりますが、すべてのグラフの相対的な比率は保たれます。 |
JavaScript エンコード スクリプト
実際に使用する場合は、おそらく手動でデータをエンコードするよりもプログラムによってデータをエンコードしたほうが簡単です。
次の JavaScript スニペットは、1 つのシリーズをシンプルまたはextendedエンコードにエンコードし、そのエンコードの完全な範囲に収まるようにデータ値をスケーリングします。データは正の数の配列として指定する必要があります。指定された正の数以外の値は、アンダースコア文字（_）を使用して欠損値としてエンコードされます。
var simpleEncoding =
'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
// This function scales the submitted values so that
// maxVal becomes the highest value.
function simpleEncode(valueArray,maxValue) {
var chartData = ['s:'];
for (var i = 0; i < valueArray.length; i++) {
var currentValue = valueArray[i];
if (!isNaN(currentValue) && currentValue >= 0) {
chartData.push(simpleEncoding.charAt(Math.round((simpleEncoding.length-1) *
currentValue / maxValue)));
}
else {
chartData.push('_');
}
}
return chartData.join('');
}
// Same as simple encoding, but for extended encoding.
var EXTENDED_MAP=
'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-.';
var EXTENDED_MAP_LENGTH = EXTENDED_MAP.length;
function extendedEncode(arrVals, maxVal) {
var chartData = 'e:';
for(i = 0, len = arrVals.length; i < len; i++) {
// In case the array vals were translated to strings.
var numericVal = new Number(arrVals[i]);
// Scale the value to maxVal.
var scaledVal = Math.floor(EXTENDED_MAP_LENGTH *
EXTENDED_MAP_LENGTH * numericVal / maxVal);
if(scaledVal > (EXTENDED_MAP_LENGTH * EXTENDED_MAP_LENGTH) - 1) {
chartData += "..";
} else if (scaledVal < 0) {
chartData += '__';
} else {
// Calculate first and second digits and add them to the output.
var quotient = Math.floor(scaledVal / EXTENDED_MAP_LENGTH);
var remainder = scaledVal - EXTENDED_MAP_LENGTH * quotient;
chartData += EXTENDED_MAP.charAt(quotient) + EXTENDED_MAP.charAt(remainder);
}
}
return chartData;
}
データをエンコードするには、simpleEncode 関数または extendedEncode 関数を呼び出して、データを含む配列（valueArray）とデータの最大値（maxValue）を渡します。最大値とグラフの上部の間にスペースを作るには、次のように maxValue をデータ配列の最大値よりも大きくします。
var valueArray = new Array(0,1,4,4,6,11,14,17,23,28,33,36,43,59,65); var maxValue = 70; simpleEncode(valueArray, maxValue);