Datenformate

In diesem Dokument wird erläutert, wie Sie Ihre Diagrammdaten an das Google Chart API senden.

Inhaltsverzeichnis

1. Übersicht
2. Basistextformat
3. Textformat mit automatischer Skalierung
4. Textformat mit benutzerdefinierter Skalierung
5. Einfaches Codierungsformat
6. Erweitertes Codierungsformat
7. Datenskalierung und Achsenskalierung
8. JavaScript-Codierungsskript

Überblick

Daten für fast alle Diagramme werden über den Parameter chd gesendet. Die Daten müssen in einem der folgenden Formate gesendet werden:

• Das Basistextformat ist im Wesentlichen einfache Gleitkommazahlen von 0 bis 100 (einschließlich). Dieses Format lässt sich leicht von Hand lesen und schreiben.
• Im Textformat mit automatischer Skalierung wird das Diagramm an Ihre Daten angepasst.
• Das Textformat mit benutzerdefinierter Skalierung ähnelt dem einfachen Textformat, ermöglicht jedoch die Angabe eines benutzerdefinierten Bereichs mithilfe eines zweiten URL-Parameters.
• Mit dem einfachen Codierungsformat können Sie ganzzahlige Werte von 0 bis 61 (einschließlich) angeben, die durch ein einzelnes alphanumerisches Zeichen codiert sind. Diese Codierung führt zum kürzesten Datenstring eines der Datenformate (falls Werte größer als 9 sind).
• Mit dem erweiterten Codierungsformat können Sie ganzzahlige Werte von 0 bis 4.095 (einschließlich) angeben, die durch zwei alphanumerische Zeichen codiert sind. Die erweiterte Codierung eignet sich am besten für ein Diagramm mit vielen Daten und einem großen Datenbereich.

Die Datenwerte werden entsprechend dem verwendeten Format skaliert. Informationen dazu, wie die Daten an das Diagramm angepasst werden, finden Sie unter Datenskalierung und Achsenskalierung.

Wir stellen ein JavaScript-Snippet zur Verfügung, um Daten in einfachen Codierungs- oder erweiterten Codierungsformaten zu codieren. Alternativ haben mehrere Mitglieder der Google-Diagrammgruppe andere Bibliotheken beigesteuert, die Ihnen bei der Formatierung helfen: Sie können in den Archiven nach ihnen suchen.

Einfaches Textformat

Mit einfachen textformatierten Daten können Sie Gleitkommawerte zwischen 0 und 100 als Zahlen angeben. Werte unter null werden als fehlend gekennzeichnet. Werte über 100 werden auf 100 gekürzt. Der Vorteil des einfachen Textformats besteht darin, dass die Werte in der URL leicht zu lesen und zu verstehen sind und dass die Beschriftungen der Standardachsen die Datenwerte korrekt darstellen. Die Textformatierung (einfach oder mit benutzerdefinierten Parametern) führt jedoch zum längsten Datenstring aller Formate.

Wenn Ihre Daten Werte außerhalb des für die Textformatierung angegebenen Bereichs enthalten, können Sie die Daten skalieren, indem Sie sie in Prozentsätze des größten Werts in Ihren Daten umwandeln. Alternativ können Sie die Skalierung durch Textformatierung mit benutzerdefinierter Skalierung übernehmen.

Syntax:

chd=t:val,val,val|val,val,val...

<data>

Jede Reihe besteht aus einem oder mehreren kommagetrennten Werten. Trennen Sie mehrere Reihen durch einen senkrechten Strich (|). Die Werte sind Gleitkommazahlen zwischen 0 und 100. Werte kleiner als null oder der Unterstrich ( _) werden als Nullwerte betrachtet. Werte über 100 werden auf 100 gekürzt.

 

Example:

Eine Tabelle mit fünf Werten. Der Unterstrich gilt als Nullwert, der Wert -30 unterschreitet den Mindestwert und wird daher ausgelassen und der Wert 200 wird auf 100 gekürzt.

chd=t:_,30,-30,50,80,200

Nach oben

Textformat mit automatischer Skalierung

Einige Diagramme lassen sich so konfigurieren, dass sie automatisch an ihre Daten angepasst werden. Das Diagramm wird so skaliert, dass sich der größte Wert oben im Diagramm und der kleinste (oder null, wenn alle Werte größer als null sind) ganz unten befindet.

Alle Markierungswerte im Diagramm zeigen die tatsächlichen Werte an, nicht die skalierten Werte.

Diese Funktion kann nur für textformatierte Werte und nicht für alle Diagrammtypen verwendet werden. Experimentieren Sie mit Ihrem Diagrammtyp, um herauszufinden, ob er unterstützt wird.

Syntax

cht=t:val,val,val...
chds=a

Beispiele:

chd=t:5,30,50,80,200 chds=a Für Kreisdiagramme dürfen keine Werte < 0 verwendet werden.

chd=t:-5,30,-30,50,80,200 chds=a

Nach oben

Textformat mit benutzerdefinierter Skalierung

Im Textformat mit benutzerdefinierter Skalierung können Sie beliebige positive oder negative Gleitkommazahlen in Kombination mit einem Skalierungsparameter angeben, mit dem Sie einen benutzerdefinierten Bereich für Ihr Diagramm angeben können. Dieses Diagramm ist nützlich, wenn Sie sich keine Gedanken darüber machen möchten, wie Sie Ihre Daten auf einen bestimmten Bereich beschränken oder die Daten nicht manuell skalieren möchten, damit sie gut in ein Diagramm passen. Bei diesem Format wird die Nulllinie bei Bedarf angepasst. Das Format der Daten entspricht dem des einfachen Textformats.

Geben Sie für Autoscaling chds=a an.

Die Textformatierung (einfach oder mit benutzerdefinierten Parametern) führt zum längsten Datenstring aller Formate.

Syntax:

Für die Textformatierung mit benutzerdefinierter Skalierung sind zwei Parameter erforderlich:

chd=t:val,val,val|val,val,val
chds=<series_1_min>,<series_1_max>,...,<series_n_min>,<series_n_max>

chd=t:<data>

Wie bei reinem Datenformat: ein oder mehrere kommagetrennte Werte pro Reihe, wobei mehrere Reihen durch ein Pipe-Zeichen (|) voneinander getrennt sind. Der Bereich der zulässigen Werte in jeder Reihe wird mit dem Parameter chds angegeben.

CHD

Ein oder mehrere zulässige Mindest- und Höchstwerte für jede Datenreihe, die durch Kommas getrennt sind. Sie müssen sowohl ein Maximum als auch ein Minimum angeben. Wenn Sie weniger Paare bereitstellen, als Datenreihen vorhanden sind, wird das letzte Paar auf alle verbleibenden Datenreihen angewendet. Der Achsenbereich ändert sich dadurch nicht. Sie müssen den Parameter chxr festlegen, um den Achsenbereich zu ändern. Gültige Werte reichen von (+/-)9,999e(+/-)199. Sie können Werte in Standard- oder E-Notation angeben.

<series_1_min>

Der minimal zulässige Wert in der ersten Reihe. Niedrigere Werte werden als fehlend markiert.

<series_1_max>

Maximal zulässiger Wert in der ersten Reihe. Höhere Werte werden auf diesen Wert gekürzt.

 

Example:

Ein Balkendiagramm mit einer Mindest-/Höchstskala von -80–140 Die Werte 30, -60, 50, 140 und 80 fallen innerhalb der Skala und werden nicht abgeschnitten. Beachten Sie, dass die Nulllinie für Sie angepasst wird, also 80 ÷ (140 + 80) = 0,36 der Höhe auf der Y-Achse. Beachten Sie außerdem, dass der Standardbereich der Y-Achse trotz des Parameters chds zwischen 0 und 100 liegt. Die Labelwerte spiegeln daher nicht die tatsächlichen Datenwerte wider.

chd=t:30,-60,50,140,80,-90 chds=-80,140

Nach oben

Einfaches Codierungsformat

Mit dem einfachen Codierungsformat können Sie Ganzzahlwerte von 0 bis 61 (einschließlich) angeben, die durch ein einzelnes alphanumerisches Zeichen codiert sind. Dies führt zur kürzesten Datenstring-URL aller Datenformate. Wenn Sie jedoch ein Linien- oder Balkendiagramm mit einer Länge von mehr als 100 Pixeln entlang der Datenachse haben, sollten Sie ein anderes Format verwenden. Da nur 62 Datenwerte unterstützt werden, ist der Detaillierungsgrad der Daten viel größer als der Anzeigegrad und die Werte sind nur geringfügig abweichend (nicht viel, aber in größeren Diagrammen sichtbar).

Wenn Sie den Parameter chds mit einfacher Codierung verwenden, wirkt sich dies nicht auf die Größe des Datenelements im Diagramm aus, aber auf alle Werte für die Datenpunktmarkierung.

Syntax:

chd=s:
  <series_1>
    ,...,
  <series_n>

<series_1>

Ein String, bei dem jedes Zeichen ein einzelner Datenpunkt ist und die Reihen durch ein Komma getrennt sind. Einzelne Werte innerhalb einer Reihe werden nicht getrennt. Folgende Datenzeichen und ihre zugehörigen Werte werden unterstützt:

• A—Z, wobei A = 0, B = 1 usw. ist, bis Z = 25
• a—z, wobei a = 26, b = 27 usw., bis z = 51
• 0(zero)—9, wobei 0 = 52 und 9 = 61
• Der Unterstrich (_) weist auf einen fehlenden Wert hin.

Mit dem folgenden Tool können Sie einen einzelnen Wert codieren oder mit dem JavaScript-Code einen ganzen URL-String skalieren und codieren.

Example:

Entspricht dem textcodierten String 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="Gestapeltes Balkendiagramm mit zwei Serien und jeweils sechs Werten, einfache Codierung." chd=s:BTb19_,Mn5tzb

Nach oben

Erweitertes Codierungsformat

Mit dem erweiterten Codierungsformat können Sie ganzzahlige Werte von 0 bis 4.095 (einschließlich) angeben, die durch zwei alphanumerische Zeichen codiert sind. Die Syntax unterscheidet sich geringfügig von der einfachen Codierung.

Wenn Sie den Parameter chds mit einfacher Codierung verwenden, wirkt sich dies nicht auf die Größe der Datenelemente im Diagramm aus, aber auf alle Werte der Datenpunktmarkierung.

Syntax:

chd=e:
  <series_1>
    ,...,
  <series_n>

<Series_1>

Ein String, bei dem jeweils zwei Zeichen ein einzelner Datenpunkt sind, und die durch ein Komma getrennt sind. Einzelne Werte in einer Reihe werden nicht getrennt. Folgende Codierungszeichen werden unterstützt:

• A—Z
• a—z
• 0—9
• Punkt (.)
• Bindestrich (-)
• Fehlende Werte werden durch einen doppelten Unterstrich (__) gekennzeichnet.

Im Folgenden finden Sie eine abgekürzte Beschreibung codierter Werte:

• AA = 0, AB = 1 usw. bis AZ = 25
• Aa = 26, Ab = 27 usw. bis Az = 51
• A0 = 52, A1 = 53 usw. bis A9 = 61
• A- = 62, A. = 63
• BA = 64, BB = 65 usw. bis BZ = 89
• Ba = 90, Bb = 91 usw. bis Bz = 115
• B0 = 116, B1 = 117 usw. bis B9 = 125
• B- = 126, B. = 127
• 9A = 3.904, 9B = 3.905 usw. bis 9Z = 3.929
• 9a = 3.930, 9b = 3.931 usw. bis 9z = 3.955
• 90 = 3.956, 91 = 3.957 usw. bis 99 = 3.965.
• 9- = 3.966, 9. = 3.967
• -A = 3.968, -B = 3.969 usw. bis -Z = 3.993
• -a = 3.994, -b = 3.995 usw. bis -z = 4.019
• -0 = 4.020, -1 = 4.021 usw. bis -9 = 4.029
• -- = 4.030, -. = 4.031
• .A = 4.032, .B = 4.033 usw. bis .Z = 4.057
• .a = 4.058, .b = 4.059 usw. bis .z = 4.083.
• .0 = 4.084, .1 = 4.085 usw. bis .9 = 4.093.
• .- = 4.094, .. = 4.095

Mit dem folgenden Tool können Sie einen einzelnen Wert codieren oder mit dem JavaScript-Code einen ganzen URL-String skalieren und codieren.

Example:

Entspricht dem textcodierten String chd=t:90,1000,2700,3500|3968,-1,1100,250

chd=e:BaPoqM2s,-A__RMD6

Nach oben

Datenskalierung und Achsenskalierung

Die Daten werden entweder explizit (bei Verwendung des Textformats mit benutzerdefinierter Skalierung) oder implizit (alle anderen Typen) an Ihr Diagramm angepasst. Das bedeutet, dass jedes Diagramm so skaliert wird, dass es in den verfügbaren Bereich des Formats passt, nicht an den tatsächlichen Bereich der von Ihnen bereitgestellten Daten.

Sie können Ihre Daten so skalieren, dass sie den gesamten Wertebereich umfassen, der für Ihr Format zulässig ist, um Unterschiede deutlicher zu machen. Sie können die Daten entweder skalieren, damit sie in das von Ihnen verwendete Format passen, oder indem Sie den Datenbereich explizit angeben (also das Textformat mit benutzerdefinierter Skalierung verwenden).

Die Werte der Achsenlabel werden auf einer völlig unabhängigen Skala berechnet und haben nichts mit den Datenwerten zu tun. Sie verwenden jedoch den Standardbereich von 0–100. Sie können diesen Bereich jedoch ändern.

In diesem Abschnitt werden beide Probleme beschrieben.

Die Daten werden an den Formatbereich angepasst [Alle Diagramme außer Kreisdiagramm und Venn]

Unterschiedliche Formate unterstützen unterschiedliche Wertebereiche. Die Daten werden entsprechend Ihrem Formatbereich skaliert, sodass der von Ihrem Format unterstützte Höchstwert oben auf der Achse und der Mindestwert für Ihr Format unten gerendert wird. Die folgenden Beispiele zeigen denselben Wert (100) mit einem einfachen Textformat (Bereich 0–100), Text mit benutzerdefinierter Skalierung (benutzerdefinierter Bereich von 0–200) und einem erweiterten Codierungsformat (Bereich 0–4095).

Einfaches Textformat	Textformat mit benutzerdefinierter Skalierung	Erweitertes Codierungsformat
Wert: 100 (chd=t:100) Formatbereich: 0–100 Die 100 wird als 100/100 in der oberen Skala gerendert.	Wert 100 (chd=t:100, chds=0,200) Formatbereich: 0–200 Die 100 wird 100/200 in der höheren Skala gerendert.	Wert: 100 (chd=e:Bk) Formatbereich: 0–4.095 Der Wert 100 wird in der Skala als 100/4095 ausgegeben.

Eine einfache Möglichkeit, Ihre Daten an Ihr Diagramm anzupassen, ist die Verwendung eines Textformats mit Skalierung. Eine aufwendigere Methode besteht darin, die Daten manuell zu skalieren, damit sie in den von Ihrem Format unterstützten Bereich passen.

Kreisdiagramme: Bei Kreisdiagrammen und Mengendiagrammen sind alle Werte relativ zueinander und nicht zur Gesamtskala des Diagramms.

chd=e:BkDIEs	chd=t:100,200,300 chds=0,300

Der Bereich des Achsenlabels wird unabhängig voneinander berechnet [Balken, Linien, Radar, Streu und Kerzendiagramm]

Mit dem Parameter chxt können Sie Achsenwerte anzeigen lassen. Allerdings ist zu beachten, dass Achsenlabels nicht entsprechend den Diagrammdaten berechnet werden, sondern entweder unabhängig von der API berechnet oder explizit von Ihnen angegeben werden.

Der Standardachsenbereich ist 0–100, unabhängig von Datenwerten oder Datenskalierung. Wenn Sie beispielsweise die Y-Achse mit den Standardbeschriftungen der Achse in einem Diagramm mit erweiterter Codierung (Bereich 0–4095) anzeigen, werden die Labels der Y-Achse weiterhin 0–100 angezeigt, es sei denn, Sie ändern dies explizit, wie unten erläutert. Das folgende Beispiel zeigt die Standardlabels der Y-Achse in einem Balkendiagramm für die erweiterte Codierung mit einem Datenwert von 100:

chd=e:Bk (entspricht chd=t:100)

Sie können den Achsenbereich jedoch mit dem Parameter chxr angeben. Wenn die Achsenwerte tatsächliche Datenwerte widerspiegeln sollen, müssen Sie die Mindest- und Höchstwerte für die Achsen entsprechend Ihrem Formatbereich angeben. Das Basistextformat hat bereits eine Skala von 0–100. Wenn Sie also eine einfache Textformatierung (ohne benutzerdefinierte Skalierung) verwenden, entsprechen die Achsenwerte standardmäßig den Datenwerten. Sehen wir uns das anhand einiger Beispiele an. Hier sind drei Diagramme mit denselben Daten (15,26,51,61), aber unterschiedlichen Formaten und unterschiedlichen Achsenskalierungen:

Einfache Codierung, keine Achsenskalierung	Einfache Codierung, skalierte Achse	Einfacher Text, keine Achsenskalierung
chd=s:Paz9   Wertebereich für einfache Codierung: 0–61 Standardachsenbereich (0–100) Der Codierungsbereich ist kleiner als der Labelachsenbereich, sodass die Balken nicht dem tatsächlichen Wert auf dem Achsenlabel entsprechen. Die Balken sind jedoch im richtigen Verhältnis zueinander.	chd=s:Paz9     chxr=0,0,61,10 Wertebereich für einfache Codierung: 0–61 Achsenbereich explizit auf 0–61 festgelegt Codierungsbereich und Achsenbereich sind gleich, sodass die Balken ihrem korrekten Wert auf der Achse entsprechen.	chd=t:15,26,51,61   Wertebereich für das einfache Textformat: 0–100 Standardachsenbereich (0–100) Codierungsbereich und Achsenbereich sind ebenfalls identisch, sodass auf der Achse standardmäßig die genauen Datenwerte angezeigt werden. Da der Bereich des Textformats größer ist als der Bereich für das einfache Codierungsformat (100 Einheiten im Vergleich zu 61 Einheiten), sind die Balken hier kleiner als in den anderen Diagrammen, aber alle Diagramme bleiben im Verhältnis zueinander.

Nach oben

JavaScript-Codierungsskript

In der Praxis ist es wahrscheinlich einfacher, Daten programmatisch als manuell zu codieren.

Das folgende JavaScript-Snippet codiert eine einzelne Reihe in eine einfache oder extended Codierung und skaliert Datenwerte so, dass sie in den gesamten Bereich dieser Codierung passen. Die Daten müssen als Array positiver Zahlen angegeben werden. Jeder Wert, der keine positive Zahl ist, wird mithilfe des Unterstrichs (_) als fehlender Wert codiert.

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;
}

Rufen Sie zum Codieren von Daten die Funktion simpleEncode oder extendedEncode auf und übergeben Sie das Array, das Ihre Daten (valueArray) enthält, sowie den Maximalwert Ihrer Daten (maxValue). Um Platz zwischen dem höchsten Wert und dem oberen Rand des Diagramms zu schaffen, legen Sie maxValue so fest, dass es größer als die größte Zahl im Datenarray ist:

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);

Nach oben