Hello World de l’API Google Chart

Pour démontrer toute la puissance et la simplicité de l’API, voici le Hello Word! tel qu’il est présenté par la documentation officielle de Google :

<img src="http://chart.apis.google.com/chart?cht=p3&chd=t:60,40&chs=250x100&chl=Hello|World" title="Hello World Google Chart" alt="Hello World Google Chart" />

qui effectue le rendu suivant :

Vous pouvez cliquer sur cette image pour la visionner en 650×350 px. Seul le paramètre chs de l’URL a été modifié pour arriver à ce résultat.

Fonctionnement et limitations

Comme on vient de le constater, le fonctionnement est simple puisqu’il est basé sur une requête GET vers le serveur de l’API. Chaque requête conforme retourne une image au format PNG. L’image demandée ne doit pas dépasser une aire de 300000 pixels et un côté ne peut dépasser 1000 pixels.

Un graphique de type mappemonde ne peut quant à lui pas dépasser les dimensions de 440×220 pixels.

Chaque graphique demandé est hautement configurable selon les paramètres transmis dans la requête. En outre, il est possible de définir le type de graphique, sa taille, les couleurs,  un titre, une légende, une grille, les espacements, la dimension des éléments, et beaucoup plus encore.

Il est aussi a noté que Google se réserve le droit de bloquer l’utilisation à son service à tout moment s’il juge son utilisation abusive. En outre, si vous juger que votre site risque d’effectuer plus de 250000 requêtes journalières vers l’API, il est recommandé de les contacter sur chart-api-notifications@google.com.

Note : cet article ne fait que présenter simplement l’API et ne pourrait se substituer à la documentation officielle fourni par Google qui elle seule vous permettra d’élaborer des graphiques aussi proches de ceux que vous désireriez présenter. Je ne peux que vous conseiller de la lire attentivement afin d’apréhender toutes les possibilités offertes par l’API.

Définir la taille du graphique

La taille du graphique désirée est définie par le paramètre chs. C’est un paramètre obligatoire qui, s’il est omis, retournera un code d’erreur HTTP 400. La valeur doit être formatée avec la largeur et la hauteur séparées par un x. Vous pouvez ne spécifier qu’une seule valeur auquel cas le graphique aura un format carré.

Comme stipulé ci-dessus, le graphique ne doit pas dépasser 300000 pixels, et un côté ne doit pas faire plus de 1000 pixels, sauf pour un graphique de type mappemonde qui ne peut dépasser 440×220 pixels.

Les types de graphiques disponibles

Le paramètre cht permet de définir le type de graphique que l’on désire afficher. Google en met 9 principaux à disposition qui ont chacun leurs propres variantes selon le paramétrage de la requête effectuée. Voici la liste des types de graphiques avec pour chaque la/les valeurs possibles. Vous pouvez cliquer sur une valeur pour avoir un aperçu de chaque type :

• courbes/lignes : lc, ls, lxy ;
• histogrammes/barres : bhs, bvs, bhg, bvg;
• secteurs ou camemberts : p, p3, pc;
• diagrammes de Venn : v;
• points ou bulles : s;
• radars : r, rs;
• mappemonde/cartes : t;
• Google-o-meters : gom;
• QR codes : qr.

Ces types de graphiques devraient couvrir la plupart des utilisations, d’autant que Google en rajoute de temps en temps.

Ajouter un titre à vos graphiques

Vous avez la possibilité d’ajouter un titre à votre graphique en utilisant le paramètre chtt. Utiliser le caractère « + » pour mettre un espace et le caractère pipe « | » pour effectuer un retour à la ligne.

Ajoutons simplement un titre à notre « Hello World! » précédent avec le code suivant :

<img src="http://chart.apis.google.com/chart?cht=p3&chd=t:60,40&chs=250x100&chl=Hello|World&chtt=Google+Chart|Hello+World+!" title="Hello World Google Chart" alt="Hello World Google Chart" />

On remarque bien évidement que les dimensions de l’image retournée correspondent toujours à celles spécifiées (250×100 pixels), et donc que le graphique en lui même a été rétréci afin de concéder la place nécessaire au titre. Il faudra alors penser à prendre en concidération ce paramètre dans le dimensionnement de votre graphique.

Couleur et taille du titre

La couleur et la taille de la police du titre peuvent être définies avec le paramètre chts. Il prend comme valeur la couleur désirée au format héxadécimal et la taille de la police séparées par une virgule :

<img src="http://chart.apis.google.com/chart?cht=p3&chd=t:60,40&chs=250x100&chl=Hello|World&chtt=Google+Chart|Hello+Word+!&chts=ff9900,9" title="Hello Word Google Chart" alt="Hello Word Google Chart" />

Malheureusement, autant il est possible d’omettre la valeur de la taille de la police, auquel cas c’est celle par défaut qui est utilisée (14), mais on ne peut spécifier cette taille sans préciser la couleur de celle-ci.

Légende et position de la légende

Tout comme il est possible d’ajouter un titre, l’API permet d’insérer une légende ainsi que de la positionner sur l’image. C’est le paramétre chdl qui défini les termes de la légende. Voici ce que celà donne, toujours sur l’exemple de notre « Hello, World! » :

Par défaut, la légende est placée sur la droite de l’image. On peut modifier la valeur du paramètre chdlp afin de positionner notre légende sur notre image. Les valeurs de ce paramètre sont prédéfinie ,s et sont au nombre de 6 :

• alignement horizontal :
  • en dessous du graphique : b;
  • au dessus du graphique : t;
• alignement vertical :
  • en dessous du graphique : bv;
  • au dessus du graphique : tv;
  • à droite du graphique (valeur par défaut) : r;
  • à gauche du graphique : l.

Gestion des couleurs

Vous pouvez laisser Google gérer lui-même les couleurs mais dans bien des cas, vous voudrez probablement définir vous-même les couleurs de vos graphiques. Il est possible de régler la majorité des couleurs pour votre image : graphique, fond, titre, lignes, … Il serait fastidieux de présenter un exemple de chaque cas possible, cependant, le paramétrage s’effectue toujours de la même façon : il faut fournir une couleur encodée au format héxadécimal :

• 000000 : noir;
• FFFFFF : blanc;
• FF0000 : rouge;
• 00FF00 : vert;
• 0000FF : bleu.

Vous pouvez optionnellement gérer un canal alpha, vous permettant de jouer avec l’opacité de la couleur, en l’ajoutant à la valeur de la couleur :

• 00000088 : noir opaque à 50%;
• FF000000 : rouge complètement transparent
• FF0000FF : rouge complètement opaque

Pour conclure !

Car il serait impossible d’énumérer toutes les possibilités qu’offre Google Chart API! Nous venons de ne voir qu’une maigre facette proposée par l’API, mais qui, j’en suis sûr, vous aura donné autant envie que moi d’aller puiser dans l’abondante documentation afin de se rendre compte de toutes les possibilité de l’API.

Pour information, il est à noter que Google utilise cette API en interne pour beaucoup d’autres services, tel que Google Analytics, Google Webmaster Tools ou encore Feed Burner.