im web gefunden

Im Herbst 2007 veröffentlichte Google seine Chart-API mit der es möglich ist, schnell diverse Diagramme online zu erstellen, um sie dann zum Beispiel in Webseiten zu integrieren.

Der Funktionsumfang reicht vom einfachen Liniendiagramm über Barcharts bis zu dreidimensionalen Tortendiagramm wie in obigem Beispiel. Ebenso sind aber auch komplizierte Diagramme mit mehreren Wertereihen und Spezialformen möglich.

In diesem Tutorial soll es hauptsächlich darum gehen, die API besser zu verstehen und Fallstricke zu vermeiden, um möglichst schnell zum gewünschten Ergebnis zu kommen.

Die Kodierung der Datenreihen verstehen

Um erfolgreich Diagramme erzeugen zu können, muss man als erstes verstehen, wie die eigenen Daten an die API übergeben und dargestellt werden.

Hintergründe

Die Diagramme werden durch den Aufruf einer URL in der Form:

http://chart.apis.google.com/chart?<parameter 1>&<parameter 2>&<parameter n>

erzeugt. Für die Länge einer URL gelten aber von System zu Sytem unterschiedliche Begrenzungen. Daher müssen die eigenen Daten in ein spezielles Format übertragen werden, das dafür sorgt, dass die URL nicht zu lang wird. Um das zu erreichen gibt es die:

Arten der Datenkodierung

Die API kennt grundsätzlich die folgenden drei Arten um eigene Datenreihen zu kodieren:

• Simple Encoding
• Text Encoding
• Extended Encoding

Jede Kodierung hat dabei einen bestimmten Wertebereich, in den die eignen Daten transformiert werden müssen. Und um die Verwirrung komplett zu machen, ist das Ganze unabhängig von den Achsenbeschriftungen und Skalierungen. Aber schauen wir uns zuerst mal an, was dass für uns bedeutet.

Die Umrechnung am Beispiel von Simple Encoding erklärt

Diese Art der Datenkodierung kennt 62 unterschiedliche Werte, die über zwei mal 26 Buchstaben und die Ziffern 0 bis 9 dargestellt werden. Der Buchstabe A repräsentiert die Zahl 0. Das große Z die Zahl 25. Das kleine a die 26 und das kleine z die 51. Die restlichen Werte entstehen durch die Ziffern 0 bis 9. Die Ziffer 0 steht für einen Zahlenwert von 52 und 9 für 61.

Aber was bedeutet das nun konkret? Ein Beispiel soll es verdeutlichen. Wir wollen folgende Tabelle als Chart darstellen.

Monat	Wert
Jan	40
Feb	10
Mär	60
Apr	30
Mai	25

Der Wert 40 wird durch den Kleinbuchstaben o dargestellt. 10 ist das große K, 60 ist die 8 und so weiter. Das heißt, dass unsere obige Zahlenreihe nach der Übersetzung die Zeichenkette oK8eZ ist. Diese Zeichenkette ist dann der Parameter chd=s:oK8eZ für unser Diagramm, das rechts zu sehen ist.

Was aber nun, wenn es Werte gibt, die größer als 61 sind und damit den vorgegebenen Wertebereich überschreiten? Zum Beispiel so:

Monat	Wert
Jan	40
Feb	30
Mär	90
Apr	20
Mai	70

Die Lösung dafür lautet, dass wir unsere Werte so umrechnen müssen, dass sie wieder in den Wertebereich von 0 bis 61 passen. Im Beispiel erledigen wir das einfach dadurch, dass wir durch 2 dividieren. Damit ergibt sich die folgende Tabelle:

Monat	Originalert	umgerechneter Wert	Zeichen
Jan	40	20	U
Feb	30	15	P
Mär	90	45	t
Apr	20	10	K
Mai	70	35	j

Unser Chart sieht damit so aus (zur Verdeutlichung habe ich rechts die errechneten Werte mit dargestellt):

Auch wenn es jede Menge Tools gibt, die einem diese Umrechnung abnehmen, hier geht es darum zu verstehen, wie es funktioniert. Denn es ergeben sich Folgeprobleme wie zum Beispiel die Skalierung und der Wertebereich der Achsen. Hat man aber verstanden, wie die Chart-API Daten behandelt, ist es ziemlich einfach auch solche Folgeprobleme zu lösen.

Nehmen wir ein anderes Beispiel, um noch einmal auf den Umgang mit dem Wertebereich zurück zu kommen. Man stelle sich vor, dass man ein Tortendiagramm darstellen möchte, in dem es um eine Aufteilung von 75% zu 25% geht.

Auf alle Fälle überschreitet 75 unseren Wertebereich von maximal 61. Als Zahlenwerte dürfen aber nur Ganzzahlen zum Einsatz kommen. Das heißt, dass eine Division durch 10 mit den Ergebnissen von 7,5 und 2,5 so nicht darstellbar wäre. Wir müssten runden. Zum Beispiel auf 8 und 2 oder 7 und 3. Das entspräche aber wiederum einer prozentualen Verteilung von 80 zu 20 oder 70 zu 30. Beides ist nicht was wir wollen. Unsere Tortendiagramme würden so aussehen:

Um zur richtigen Verteilung zu kommen, verdoppeln wir einfach unseren ersten Ergebnisse von 7,5 und 2,5 und erhalten 15 und 5. Und schon haben wir unser Verhältnis von 75% zu 25% sauber abgebildet, wie weiter oben zu sehen ist.

Y-Achsen richtig darstellen

Bleiben wir beim simple Encoding unserer Datenreihen. Die Google-Chart-API erwartet über den zwingend notwendigen Parameter chs eine Größenangabe für unser Diagramm. Die Syntax lautet:

chs=<Breite in Pixeln>x<Höhe in Pixeln>

chs=300x200 erzeugt ein Chart in der Größe von 300x200 Pixeln

Wir haben beim simple Encoding den Wertebereich von 0 bis 61 - also 62 unterschiedliche Werte. Was bedeutet das nun bezogen auf eine Charthöhe von 200 Pixeln. Zwei Dinge:

1. Jedem Datenwert stehen theoretisch 2,9 Pixel zur Verfügung. Man kann ein Pixel aber nicht teilen. Also wird die ganze Sache schon hier etwas ungenau.
2. Der Wert von 61 wird an der oberen Bildgrenze, also bei 200 Pixeln liegen. Vorausgesetzt wir benutzen keinen Diagrammtitel. Die verbleibenden Pixel werden gleichmäßig auf die anderen 61 (ja 61 und nicht 60) Werte verteilt. Wobei noch eventuell die Beschriftung(en) für die x-Achse hinzukommt.

Wie sieht es nun aus, wenn wir Werte von 0 bis 100 mit der Chart-API von Google darstellen wollen? Uns bleibt im ersten Schritt nichts weiter übrig, als alles auf den Maximalwert von 60 zu beziehen. 60 entsprechen dem zu Folge 100%, also 100. Damit ergibt sich aber, dass wir in einem linearen Diagramm nicht alle Werte darstellen können. Besser eignet sich hier ein Umrechnungswert von 0,5. Das heißt der Diagrammwert von 50 entspricht dem Realwert von 100. So können wir immerhin noch alle geraden Zahlenwerte darstellen. Dafür verschenken wir aber 11 Werte (von 50 bis 61) und unser Diagramm wird nicht bis zum oberen Rand benutzt. Der Grund dafür: Der obere Rand entspricht immer dem Maximalwert der jeweiligen Kodierung. In unserem Fall also 61.

Aber genug der Rede, schauen wir es uns an:

Links im Diagramm sind die Werte bezogen auf 60 dargestellt und rechts die auf 50 gerechneten. Die x-Achse ist der jeweilige Wert der entsprechend der Kodierung eingesetzt wird. Deutlich zu erkennen ist das besprochene Verschenken von Platz im rechten Bereich mit der 0,5 Umrechnung.

Welche Schlussfolgerungen ergeben sich daraus für die Range oder den Wertebereich der y-Achsen, also den Parameter chxr? Die linke y-Achse wurde mit einer Range von 0 bis 102 und die rechte mit einer Range von 0 bis 122 angegeben. Diese Werte sind das Ergebnis simpler Prozentrechnung:

     M   R                     M
     - = -   daraus folgt: R = - * A
     Y   A                     Y

M: maximal darzustellender Wert (hier 100)
Y: Bezugswert (hier 60 im linken Teil und 50 im rechten Teil)
A: Maximalwert der Auflösung (Simple Encoding: 61, Text Encoding: 100, Extended Encoding: 4095)
R: Rangeobergrenze

Text Encoding und Extended Encoding der Google Chart API

Grundsätzlich gilt für diese beiden Arten der Datenumwandlung das bereits gesagte.

Extended Encoding bietet mit einem Wertebereich von 4096 Werten von 0 bis 4095 den größten Werteumfang. Wenn wir bei simple Encoding immer alles auf den Wert 61 bezogen haben, müssen wir hier mit einem Bezugswert von 4095 rechnen. Um eine solche feine Abstufung aber überhaupt sichtbar machen zu können, müssen wir mit größeren Grafiken arbeiten.

Bedeutend einfacher fällt dem auf metrische Systeme geeichtem Mitteleuropäer dagegen Text Encoding. Der Wertebereich geht von 0 bis 100.0. Er umfasst insgesamt 1001 Stufen, da die erste Nachkommastelle mit ausgewertet wird. Die Google Chart API spricht ausdrücklich davon, dass die Nachkommastelle in anglophonisch typischer Form mittels Punkt (”.”) mit anzugeben ist. Es funktioniert zwar auch ohne den Punkt, aber verlassen sollte man sich nicht darauf. Daran ändert auch die Tatsache nichts, dass die Nachkommastellen selbst bei einigen von Google erstellten Beispielen fehlen. Dabei liegt genau in der Schreibweise eines der Probleme begraben: Gibt man die Nachkommastelle mit an, so produziert diese Art der Kodierung die längsten URLs. 99.0 sind vier Zeichen bei Text Encoding während die 99 mit jB mit zwei Zeichen bei Extended Encoding auskommt.

Hat man nur relativ wenige Punkte darzustellen, empfehle ich aber trotzdem Text Encoding zu benutzen. Zumal man sich damit unter Umständen die Umrechnung für die y-Achsen spart. Auf alle Fälle lassen sich die Werte für das Gitternetz leichter berechnen: Googles Chart API sagt zwar, dass es sich bei den ersten beiden Werten des Parameters chg um die Stepsize handelt. Sie verschweigt aber, dass es Prozentwerte sind, die die Darstellung des Gitternetzes beeinflussen. Und so könnte zum Beispiel ein Ergebnis mit Text Encoding und einem Gitternetz von chg=9.09,10 aussehen:

Zum Abschluss negative Zahlen

Von Haus aus kennt die ChartAPI von Google nur positive Zahlen. Was aber nun, wenn man negative Zahlen darstellen will oder muss? Es gibt verschiedene Wege, wobei ich mich für folgende Methode entscheiden würde:

Man zeichnet über den Parameter chm zusätzliche vertikale und oder horizontale Marker. Diese Marker stellen dann die jeweilige Nulllinie dar. Anschließend rechnet man seine Werte so um, dass die negativen Werte bei Benutzung von Text Encoding im Bereich von 0 bis 50 liegen. Die positiven Werte hingegen liegen im Bereich von 50 bis 100. Und so sehen dann die gezeichneten Diagramme aus:

Das Ganze hat nur den Nachteil, dass die Beschriftungen weiterhin an den ursprünglichen Achsen sind. Ideal wäre es, wenn man die Beschriftungen an den Markern anbringen und die ursprünglichen Axen ausblenden könnte. Doch das geht leider nicht.

Abschließend noch eine Idee von Stuart Langridge, der mittels Transparenzen die links stehende Darstellung für negative Zahlen benutzt. Das Ganze ist aus der nachfolgenden Grafik entstanden, in der für den unteren schwarzen Balken die Transparenz auf hundert Prozent gesetzt wurde.

Weitere Informationsquellen zur Chart-API von Google

Die erste Anlaufstelle für Informationen ist Googles Beschreibung zur Chart-API selbst. Bei Fragen hilft die Google Gruppe zur Chart-API. Die Mitglieder der Gruppe pflegen auch ein Verzeichnis mit Links zu weiteren Informationen im Netz, inklusive der Einbindung in die verschiedenen Programmiersprachen.