Cette page décrit les principes de base de l'utilisation de l'API Chart pour créer des graphiques.
Règles d'utilisation des graphiques Google
Vous pouvez effectuer un nombre illimité d'appels quotidiens vers l'API de création de graphiques Google. Nous nous réservons toutefois le droit de bloquer toute utilisation que nous considérons comme abusive.
Présentation
Afficher des graphiques dans cette documentation
Toutes les images de graphiques de cette documentation sont générées en temps réel à l'aide de l'API Chart. Pour afficher l'URL d'une image, procédez comme suit:
- Si vous utilisez Firefox, faites un clic droit et sélectionnez "Afficher l'image" ou "Propriétés".
- Si vous utilisez Internet Explorer, faites un clic droit et sélectionnez "Propriétés".
Pour faciliter la lecture d'une URL, ce document affiche souvent celle-ci sur plusieurs lignes. Lorsque vous utilisez l'API de création de graphiques Google, vous devez fournir une URL sur une seule ligne.
L'API de création de graphiques Google renvoie une image de graphique en réponse à une requête URL GET ou POST. L'API peut générer de nombreux types de graphiques, allant des graphiques en courbes ou à secteurs aux codes QR et aux formules. Toutes les informations souhaitées sur le graphique, telles que ses données, sa taille, ses couleurs et ses libellés, font partie de l'URL. (Pour les requêtes POST, c'est un peu différent, mais ne vous en faites pas pour le moment.)
Pour créer le graphique le plus simple possible, votre URL doit simplement spécifier son type, ses données et sa taille. Vous pouvez saisir cette URL directement dans votre navigateur ou pointer vers elle avec une balise <img> sur votre page Web. Par exemple, suivez ce lien pour un diagramme circulaire:
https://chart.googleapis.com/chart?chs=250x100&chd=t:60,40&cht=p3&chl=Hello|World
Le lien précédent est un exemple d'URL de base de l'API Chart. Toutes les URL des graphiques ont le format suivant:
https://chart.googleapis.com/chart?cht=<chart_type>&chd=<chart_data>&chs=<chart_size>&...additional_parameters...
Toutes les URL commencent par https://chart.googleapis.com/chart?, suivi des paramètres spécifiant les données et l'apparence du graphique. Les paramètres sont des paires nom=valeur, séparées par une esperluette (&). Les paramètres peuvent figurer dans n'importe quel ordre, après ?. Tous les graphiques nécessitent au minimum les paramètres suivants: cht (type de graphique), chd (données) et chs (taille du graphique). Cependant, il existe de nombreux autres paramètres pour les options supplémentaires, et vous pouvez spécifier autant de paramètres supplémentaires que le graphique le permet.
Examinons l'URL ci-dessus plus en détail:
| URL | Composants |
|---|---|
|
|
Copiez et collez cette URL dans votre navigateur, puis essayez d'apporter quelques modifications: ajoutez des valeurs supplémentaires aux données (n'oubliez pas d'ajouter une virgule avant chaque nouvelle valeur de données). Ajoutez de nouvelles étiquettes (placez un signe | avant chaque nouvelle valeur). Agrandir le graphique.
Créer un graphique
Voici comment créer un graphique sous forme d'images:
- Choisissez un type de graphique. Consultez la galerie pour obtenir la liste des graphiques. Le type de graphique est spécifié par le paramètre
cht. Dessinez tous les composants que vous souhaitez intégrer à votre graphique (axes, libellés, arrière-plans, etc.) et, si nécessaire, déterminez les dimensions en pixels des différents composants (taille totale du graphique, taille de la légende, etc.). Commencez par lire attentivement la documentation correspondant à votre type de graphique. Sinon, vous risquez de rencontrer une expérience frustrante. - Créer et mettre en forme les données de votre graphique Les données sont spécifiées à l'aide du paramètre
chd. Vous devez choisir le format à utiliser pour vos données :- Sélectionnez un format de données. Vous pouvez utiliser un format de texte simple, facile à lire, mais qui prend plus d'espace à envoyer, ou l'un des types d'encodage, qui est plus petit à envoyer, mais qui limite la plage de valeurs que vous pouvez envoyer.
- Déterminez si vos données doivent être ajustées pour s'adapter à votre graphique. Les formats acceptent différentes plages de valeurs. Vous pouvez effectuer un scaling des données afin qu'elles couvrent toute la plage de valeurs autorisées par votre format, afin de rendre les différences plus évidentes. Pour ce faire, vous pouvez soit mettre les données à l'échelle pour les adapter au format de données que vous utilisez, soit utiliser la mise en forme du texte avec un scaling personnalisé.
- Encodez vos données, si nécessaire. Si vous avez choisi un format encodé, nous proposons du code JavaScript pour vous aider avec d'autres types d'encodage.
- Spécifiez la taille du graphique. La taille du graphique est spécifiée à l'aide du paramètre
chs. Consultez la documentation pour connaître le format et les valeurs maximales. - Ajoutez des paramètres supplémentaires. La documentation de chaque graphique répertorie les paramètres facultatifs disponibles. Les options habituelles incluent les libellés, les titres et les couleurs. Notez que tout le texte du libellé ou du titre doit être encodé au format UTF-8. Notez que de nombreux paramètres vous permettent de saisir plusieurs valeurs. Par exemple, le paramètre
chmvous permet d'appliquer une forme à un seul point de données d'un graphique. Vous pouvez placer des formes sur plusieurs points de données à l'aide du paramètrechm, mais pour cela, vous ne spécifiez pas le paramètrechmplusieurs fois dans votre URL (par exemple, WRONG:chm=square&chm=circle&chm=triangle). Les paramètres qui acceptent plusieurs valeurs utilisent plutôt un séparateur entre plusieurs valeurs dans le même paramètre, comme une virgule ou une barre verticale. Pourchm, il s'agit d'une barre. Vous obtenez donc quelque chose comme ceci: RIGHT:chm=square|circle|triangle. Pour savoir comment spécifier plusieurs paramètres, consultez les informations détaillées sur chaque paramètre. - Créez votre chaîne d'URL. L'URL commence par
https://chart.googleapis.com/chart?et est suivie de tous les paramètres obligatoires (cht,chd,chs) et des paramètres facultatifs. Remarque:Si vous utilisez votre URL dans une balise<img>, vous devez remplacer tous les caractères&par&dans votre lien. Exemple:<img src="https://chart.googleapis.com/chart?chs=250x100&chd=t:60,40&cht=p3&chl=Hello|World" />. - Utilisez GET ou POST pour obtenir votre image. GET, se produit lorsque vous saisissez l'URL directement dans votre navigateur ou que vous l'utilisez dans une balise
<img>. Cependant, la longueur des URL est limitée à 2 Ko. Si vous disposez de plus de données ou si vous avez un goût de sang, envisagez plutôt d'utiliser la méthode POST, comme décrit ici. - Créez des régions cliquables. Si vous le souhaitez, vous pouvez créer une image cliquable pour le graphique afin d'ajouter des liens hypertexte ou de cliquer sur des éléments spécifiques. Pour en savoir plus, consultez la section Créer une image cliquable dans un graphique.
Glossaire des termes du graphique
Voici quelques termes importants que nous utilisons dans cette documentation:
- Série
- Ensemble de données associées dans un graphique.
Ce qui constitue une série dépend du type de graphique: dans un graphique en courbes, une série est une ligne unique. Dans un graphique à secteurs, chaque entrée est un secteur et tous les secteurs sont une série. Dans un graphique à barres, une série correspond à toutes les barres d'un même ensemble de données. Les différentes séries sont soit regroupées côte à côte, soit empilées les unes sur les autres, en fonction du type de graphique à barres. Le graphique suivant illustre un graphique à barres groupées avec deux séries, l'une en bleu foncé et l'autre en bleu clair:
- Libellés d'axe
- Valeurs numériques ou textuelles le long de chaque axe. Dans le graphique précédent, ce seraient les étiquettes "jan.", "févr.", "mars", "0", "50" et "100".
Composants du graphique
Voici quelques-uns des composants d’un graphique:
- Zone du graphique
- Zone affichant l'illustration de la série. Pour en savoir plus, consultez la barre latérale "Composants de graphique".
- Légende
- Petite zone du graphique décrivant la série. Dans le graphique ci-dessus, il s'agit de la section qui répertorie "Chats" et "Chiens".
- Paramètre
- Paire clé=valeur utilisée dans l'URL. Par exemple:
chxt=x, oùchxtest le nom du paramètre etxla valeur du paramètre. - GET et POST
- Deux méthodes vous permettent d'envoyer l'URL d'un graphique. La méthode GET est généralement effectuée en saisissant une URL dans le navigateur ou en en faisant la source d'un tag
<img>. Les requêtes POST sont plus complexes à effectuer, mais peuvent inclure beaucoup plus de données. La principale raison d'utiliser POST au lieu de GET est qu'une requête POST peut consommer beaucoup plus de données qu'une requête GET (16 000 caractères contre 2 000 caractères). Pour en savoir plus sur la méthode POST, cliquez ici. - Barre verticale
- Caractère
|, souvent utilisé comme délimiteur de valeurs de paramètre, c'est-à-dire un caractère permettant de séparer plusieurs valeurs. Les virgules et les esperluettes (&) sont également utilisées comme délimiteurs dans l'URL du graphique. - Graphiques composés
- Graphique combinant deux types de graphiques différents : par exemple, un graphique à barres avec une ligne ou un graphique en courbes avec des repères en chandeliers japonais. Consultez la page Graphiques composés.
Optimisations
Maintenant que vous connaissez les principes de base de la création de graphiques, voici quelques optimisations que vous pouvez utiliser.
Utiliser la méthode POST
La longueur des URL est limitée à 2 Ko. Par conséquent, si votre graphique contient plus de données, vous devez utiliser POST au lieu de GET, comme décrit ici. GET permet de saisir l'URL de votre graphique dans la barre d'adresse de votre navigateur ou de l'utiliser comme source d'un élément <img> sur une page Web. POST nécessite une programmation supplémentaire dans un autre langage, tel que PHP ou PERL.
Créer des graphiques en JavaScript
Vous pouvez utiliser l'API Google Visualization pour créer des graphiques sous forme d'images. L'API Google Visualization est une API basée sur JavaScript qui vous fournit des outils pour créer, filtrer et manipuler des données, ou pour rechercher des données dans des feuilles de calcul Google ou d'autres sites. Vous pouvez utiliser l'API de visualisation pour créer vos données, puis demander à celle-ci d'appeler l'API Image Charts pour afficher le graphique sur la page. Pour en savoir plus, consultez la documentation relative au graphique d'images génériques ou recherchez dans la galerie de visualisation les graphiques Google portant la mention (Image).