このドキュメントでは、グラフのデータを Google Chart API に送信する方法について説明します。
目次
概要
ほぼすべてのグラフのデータは、chd パラメータを使用して送信されます。データは次のいずれかの形式で送信する必要があります。
- 基本テキスト形式は、基本的には 0 ～ 100 の単純な浮動小数点数です。この形式は、手入力で簡単に読み書きできます。
- 自動スケーリングのテキスト形式を使用すると、データに合わせてグラフのサイズが変更されます。
- カスタム スケーリングのテキスト形式は、基本的なテキスト形式と似ていますが、2 つ目の URL パラメータを使用してカスタム範囲を指定できます。
- シンプルなエンコード形式: 0 ～ 61 の整数値を 1 文字の英数字で指定できます。このエンコードにより、（いずれかの値が 9 より大きい）データ形式の中で最小のデータ文字列が生成されます。
- 拡張エンコード形式では、0 ～ 4,095 の整数値を 2 文字の英数字でエンコードして指定できます。 拡張エンコードは、大量のデータがあり、データ範囲が広いグラフに最適です。
データ値は、使用する形式に合わせてスケーリングされます。グラフに合わせてデータを操作する方法については、データ スケーリングと軸スケーリングをご覧ください。
データをシンプルなエンコード形式または拡張エンコード形式でエンコードするための JavaScript スニペットを提供しています。また、Google Chart の複数のグループ メンバーが、フォーマットをサポートする他のライブラリを提供しています（アーカイブを検索してそれらを見つける）。
基本テキスト形式
基本的なテキスト形式のデータでは、0 ～ 100 の浮動小数点値を数値として指定できます。0 未満の値は欠損としてマークされ、100 を超える値は 100 に切り捨てられます。基本テキスト形式の利点は、値が URL 内で読みやすく理解しやすいことです。また、デフォルトの軸ラベルでデータ値が正確に示されます。ただし、テキスト形式（シンプルかカスタム パラメータあり）は、すべての形式の中で最も長いデータ文字列になります。
テキスト形式に指定された範囲外の値がデータに含まれている場合は、データの最大値に対するパーセンテージに変換することでデータをスケーリングできます。または、カスタム スケーリングのテキスト形式を使用して、自動的にスケーリングを処理することもできます。
構文:
chd=t:val,val,val|val,val,val...
- <データ>
- 各系列は 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パラメータで指定します。 - Chds
- 各データ系列の許容値の 1 つ以上の最小値と最大値をカンマで区切って指定します。最大値と最小値の両方を指定する必要があります。指定するペアの数がデータ系列の数より少ない場合、最後のペアが残りのすべてのデータ系列に適用されます。これによって軸の範囲は変更されません。軸の範囲を変更するには、
chxrパラメータを設定する必要があります。 有効な値の範囲は (+/-)9.999e(+/-)199 です。値は標準表記または E 表記で指定できます。- <series_1_min>
- 最初の系列の最小許容値。これより小さい値は欠損としてマークされます。
- <series_1_max>
- 最初のシリーズの最大許容値。これより大きい値はこの値に切り捨てられます。
例:
最小/最大スケールが -80 ～ 140 の棒グラフ。30、-60、50、140、80 の値はスケール内にあるため、切り捨てられません。基準線は 80/(140 + 80) = 0.36 だけ y 軸上になるように調整されています。 また、 |
|
単純なエンコード形式
シンプルなエンコード形式では、0 ～ 61 の整数値を 1 文字の英数字でエンコードして指定できます。これにより、すべてのデータ形式の中でデータ文字列の URL が最小になります。ただし、データ軸に沿って 100 ピクセルを超える折れ線グラフまたは棒グラフがある場合は、別の形式を使用したほうがいい場合があります。これは、サポートされるデータが 62 個のみであり、データの粒度が表示の粒度よりもはるかに大きく、値の差がほとんどなくなるためです（大きなグラフでは表示されますが、それほど大きな差はありません）。
シンプルなエンコードで chds パラメータを使用すると、グラフ上のデータ要素のサイズは影響を受けませんが、データポイント マーカーの値は影響を受けます。
構文:
chd=s:
<series_1>
,...,
<series_n>
- <シリーズ 1>
- 各文字が単一のデータポイントを含み、シリーズはカンマで区切られる文字列。系列内の個々の値は区切りません。 サポートされているデータ文字と、それに対応する値は次のとおりです。
A—Z（A= 0、B= 1 など）、Z= 25a—z（a= 26、b= 27 など）、z= 510(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="2 つのシリーズと 6 つの値の積み上げ棒グラフ, シンプルなエンコード。" src="/static/chart.png">chd=s:BTb19_,Mn5tzb |
拡張エンコード形式
拡張エンコード形式を使用すると、0 ～ 4,095 の整数値を 2 文字の英数字でエンコードして指定できます。単純なエンコードとは構文が若干異なります。
シンプルなエンコードで chds パラメータを使用すると、グラフ上のデータ要素のサイズは影響を受けませんが、データポイント マーカーの値には影響します。
構文:
chd=e:
<series_1>
,...,
<series_n>
- <シリーズ 1>
- 2 文字が 1 つのデータポイントであり、シリーズがカンマで区切られる文字列。系列内の各値は区切りません。サポートされているエンコード文字は次のとおりです。
A—Za—z0—9- ピリオド（
.） - ハイフン（
-） - 欠損値は 2 つのアンダースコア（
__）で示されます。
以下は、エンコードされた値の簡単な説明です。
AA= 0、AB= 1、以降もAZ= 25 となります。Aa= 26、Ab= 27、以降もAz= 51 となります。A0= 52、A1= 53、以下同様にA9= 61 になります。A-= 62、A.= 63BA= 64、BB= 65、以下同様にBZ= 89Ba= 90、Bb= 91、以降もBz= 115 となります。B0= 116、B1= 117、以下同様にB9= 125 になります。B-= 126、B.= 1279A= 3904、9B= 3905、以下同様に9Z= 39299a= 3930、9b= 3931、以下同様に9z= 395590= 3956、91= 3957、以下同様に99= 39659-= 3,966、9.= 3,967-A= 3968、-B= 3969、以下同様に-Z= 3993-a= 3994、-b= 3995、以下同様に-z= 4019-0= 4020、-1= 4021、以下同様に-9= 4029--= 4,030、-.= 4,031.A= 4032、.B= 4033、以下同様に.Z= 4057.a= 4058、.b= 4059、以下同様に.z= 4083.0= 4084、.1= 4085、以下同様に.9= 4093.-= 4,094、..= 4,095
次のツールを使用して単一の値をエンコードするか、JavaScript コードを使用して URL 文字列全体のスケーリングとエンコードを行います。
例:
テキスト エンコード文字列 chd=t:90,1000,2700,3500|3968,-1,1100,250 と同じです。 |
 chd=e:BaPoqM2s,-A__RMD6 |
データ スケーリングと軸スケーリング
データは、グラフに合わせて明示的に（カスタム スケーリングでテキスト形式を使用する場合）または暗黙的（他のすべてのタイプ）にスケーリングされます。つまり、各グラフは、提供するデータの実際の範囲ではなく、形式の使用可能な範囲に合わせてスケーリングされます。
形式によって許容される値の範囲全体に対応するようにデータをスケーリングすることで、違いを明確にできます。データをスケーリングするには、使用する形式に合わせてデータをスケーリングするか、データ範囲を明示的に指定します（つまり、カスタム スケーリングのテキスト形式を使用します）。
軸のラベルの値は完全に独立したスケールで計算され、データ値とは関係ありませんが、デフォルトの範囲（0 ～ 100）が使用されます。 この範囲は変更できます。
このセクションでは、この 2 つの問題について説明します。
データは形式範囲に合わせてスケーリングされます [円グラフとベン図を除くすべてのグラフ]
サポートされる値の範囲は形式によって異なります。データは書式範囲に合わせてスケーリングされるため、形式でサポートされる最大値がその軸の上部にレンダリングされ、形式の最小値が下部にレンダリングされます。次の例では、基本のテキスト形式（0 ～ 100）、カスタム スケーリングのテキスト（0 ～ 200 のカスタム範囲）、拡張エンコード形式（0 ～ 4,095）を使用して、同じ値（100）を使用しています。
| 基本テキスト形式 | カスタム スケーリングのテキスト形式 | 拡張エンコード形式 |
|---|---|---|
 |
 |
 |
値: 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 ～ 4,095 の範囲）を使用するグラフでデフォルトの軸ラベルを使用して 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);