Formats de données

Ce document explique comment envoyer les données de votre graphique à l'API de création de graphiques Google.

Sommaire

Présentation

Les données de presque tous les graphiques sont envoyées à l'aide du paramètre chd. Les données doivent être envoyées dans l'un des formats suivants:

• Le format de texte de base correspond essentiellement à de simples nombres à virgule flottante compris entre 0 et 100 inclus. Ce format est facile à lire et à écrire à la main.
• Le format texte avec mise à l'échelle automatique adapte le graphique à vos données.
• Le format de texte avec scaling personnalisé est semblable au format de texte de base, mais vous permet de spécifier une plage personnalisée à l'aide d'un second paramètre d'URL.
• Format d'encodage simple : permet de spécifier des valeurs entières comprises entre 0 et 61 inclus, encodées par un seul caractère alphanumérique. Cet encodage donne la chaîne de données la plus courte parmi tous les formats de données (si les valeurs sont supérieures à 9).
• Le format d'encodage étendu vous permet de spécifier des valeurs entières comprises entre 0 et 4 095 inclus, encodées par deux caractères alphanumériques. L'encodage étendu convient mieux à un graphique comportant beaucoup de données et une large plage de données.

Les valeurs des données sont mises à l'échelle pour correspondre au format utilisé. Pour en savoir plus sur la façon dont les données sont manipulées pour s'adapter au graphique, consultez la section Mise à l'échelle des données et mise à l'échelle de l'axe.

Nous fournissons un extrait de code JavaScript pour encoder les données dans des formats d'encodage simples ou étendus. Plusieurs membres du groupe Google Charts ont également fourni d'autres bibliothèques pour faciliter la mise en forme, par exemple en parcourant les archives pour les retrouver.

Format de texte de base

Les données de base au format texte vous permettent de spécifier des valeurs à virgule flottante comprises entre 0 et 100 inclus, sous forme de nombres. Les valeurs inférieures à zéro sont marquées comme manquantes. Les valeurs supérieures à 100 sont tronquées à 100. L'avantage du format de texte de base est que les valeurs sont faciles à lire et à comprendre dans l'URL, et que les étiquettes d'axe par défaut affichent les valeurs des données avec précision. Toutefois, une mise en forme du texte (simple ou avec des paramètres personnalisés) génère la chaîne de données la plus longue, tous formats confondus.

Si vos données incluent des valeurs en dehors de la plage spécifiée pour la mise en forme du texte, vous pouvez les convertir en pourcentages de la plus grande valeur de vos données. Vous pouvez également utiliser une mise en forme du texte avec mise à l'échelle personnalisée pour gérer la mise à l'échelle à votre place.

Syntaxe:

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

<data>

Chaque série se compose d'une ou de plusieurs valeurs séparées par une virgule. Séparez plusieurs séries à l'aide d'une barre verticale (|). Les valeurs sont des nombres à virgule flottante compris entre 0 et 100 inclus. Les valeurs inférieures à zéro ou le caractère de soulignement ( _ ) sont considérées comme des valeurs nulles. Les valeurs supérieures à 100 sont tronquées à 100.

 

Exemple :

Un tableau avec cinq valeurs. Le trait de soulignement est considéré comme une valeur nulle. La valeur -30 est inférieure à la valeur minimale. Elle est donc supprimée, et la valeur 200 est tronquée à 100.

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

Haut de page

Format de texte avec autoscaling

Vous pouvez configurer la mise à l'échelle automatique de certains graphiques en fonction de leurs données. Le graphique est mis à l'échelle de sorte que la plus grande valeur se trouve en haut et la plus petite (ou zéro si toutes les valeurs sont supérieures à zéro) se trouve en bas.

Toutes les valeurs de repère affichées sur le graphique afficheront leurs valeurs réelles, et non leurs valeurs mises à l'échelle.

Cette fonctionnalité n'est compatible qu'avec les valeurs au format texte. Elle n'est pas compatible avec tous les types de graphiques. Testez différents types de graphiques pour voir s'ils sont compatibles.

Syntaxe

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

Exemples :

chd=t:5,30,50,80,200 chds=a Notez que vous ne devez pas utiliser de valeurs < 0 pour les graphiques à secteurs.

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

Haut de page

Format de texte avec mise à l'échelle personnalisée

Le format de texte avec mise à l'échelle personnalisée vous permet de spécifier des nombres à virgule flottante positifs ou négatifs arbitraires, en combinaison avec un paramètre de mise à l'échelle qui vous permet de spécifier une plage personnalisée pour votre graphique. Ce graphique est utile lorsque vous ne souhaitez pas limiter vos données à une plage spécifique ou mettre à l'échelle manuellement les données pour qu'elles s'intègrent parfaitement à un graphique. Ce format ajustera automatiquement la ligne zéro, si nécessaire. Le format des données est le même que pour le format texte de base.

Pour le scaling automatique, spécifiez chds=a.

La mise en forme du texte (simple ou avec des paramètres personnalisés) génère la chaîne de données la plus longue, quel que soit le format.

Syntaxe :

La mise en forme du texte avec mise à l'échelle personnalisée nécessite deux paramètres:

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

chd=t:<data>

Identique au format de données brutes: une ou plusieurs valeurs séparées par une virgule par série, plusieurs séries séparées par une barre verticale (|). La plage de valeurs autorisées dans chaque série est spécifiée par le paramètre chds.

chds

Ensemble d'une ou plusieurs valeurs minimales et maximales autorisées pour chaque série de données, séparées par une virgule. Vous devez indiquer à la fois une valeur maximale et une valeur minimale. Si vous fournissez moins de paires qu'il n'y a de séries de données, la dernière paire est appliquée à toutes les séries de données restantes. Notez que cela ne modifie pas la plage de l'axe. Pour la modifier, vous devez définir le paramètre chxr. Les valeurs valides sont comprises entre (+/-)9,999e(+/-)199. Vous pouvez spécifier des valeurs au format standard ou en notation E.

<series_1_min>

Valeur minimale autorisée dans la première série. Les valeurs inférieures sont marquées comme manquantes.

<series_1_max>

Valeur maximale autorisée dans la première série. Les valeurs supérieures sont tronquées à cette valeur.

 

Exemple :

Graphique à barres avec une échelle minimale/maximale de -80 à 140. Les valeurs 30, -60, 50, 140 et 80 sont comprises dans l'échelle, elles ne sont donc pas tronquées. Notez que la ligne zéro est ajustée automatiquement, à hauteur de 80/(140 + 80) = 0,36 vers le haut de l'axe Y. Notez également que la plage par défaut de l'axe Y est toujours comprise entre 0 et 100, malgré le paramètre chds. Les valeurs des libellés ne reflètent donc pas les valeurs réelles des données.

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

Haut de page

Format d'encodage simple

Ce format d'encodage simple vous permet de spécifier des valeurs entières comprises entre 0 et 61 inclus, et encodées par un seul caractère alphanumérique. Cela permet d'obtenir l'URL de chaîne de données la plus courte parmi tous les formats de données. Toutefois, si votre graphique en courbes ou à barres comporte plus de 100 pixels le long de l'axe de données, vous pouvez utiliser un autre format. En effet, avec seulement 62 valeurs de données acceptées, la précision des données est beaucoup plus importante que celle de l'affichage, et les valeurs seront peu décevantes (pas beaucoup, mais visibles sur les graphiques plus grands).

Notez que si vous utilisez le paramètre chds avec un encodage simple, la taille des éléments de données du graphique ne sera pas affectée, mais toutes les valeurs des repères de point de données le seront.

Syntaxe:

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

<series_1>

Chaîne, dans laquelle chaque caractère correspond à un seul point de données, et les séries sont séparées par une virgule. Les valeurs individuelles d'une série ne sont pas délimitées. Voici les caractères de données acceptés et les valeurs correspondantes:

• A—Z, où A = 0, B = 1, et ainsi de suite, jusqu'à Z = 25.
• a—z, où a = 26, b = 27, et ainsi de suite, jusqu'à z = 51.
• 0(zero)—9, où 0 = 52 et 9 = 61
• Le trait de soulignement (_) indique une valeur manquante.

Vous pouvez utiliser l'outil suivant pour encoder une valeur unique, ou le code JavaScript pour mettre à l'échelle et encoder une chaîne d'URL complète.

Exemple :

Équivaut à la chaîne encodée au format texte 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="Graphique à barres empilées avec deux séries et six valeurs chacun, encodage simple." src="/static/chart/cht0che_image_,code_standard_s*,che_x_ dans _x/* chd=s:BTb19_,Mn5tzb

Haut de page

Format d'encodage étendu

Le format d'encodage étendu vous permet de spécifier des valeurs entières comprises entre 0 et 4 095 inclus, et encodées par deux caractères alphanumériques. Elle utilise une syntaxe légèrement différente de celle d'un encodage simple.

Notez que si vous utilisez le paramètre chds avec un encodage simple, la taille de l'élément de données sur le graphique n'est pas affectée, mais toutes les valeurs des repères de point de données le seront.

Syntaxe :

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

<série_1>

Chaîne dans laquelle deux caractères correspondent à un seul point de données et dans laquelle les séries sont séparées par une virgule. Les valeurs individuelles d'une série ne sont pas délimitées. Voici les caractères d'encodage acceptés:

• A—Z
• a—z
• 0—9
• période (.)
• Tiret (-)
• Les valeurs manquantes sont indiquées par un double trait de soulignement (__).

Voici une description abrégée des valeurs encodées:

• AA = 0, AB = 1, et ainsi de suite jusqu'à AZ = 25
• Aa = 26, Ab = 27, et ainsi de suite, jusqu'à Az = 51.
• A0 = 52, A1 = 53, et ainsi de suite, jusqu'à A9 = 61.
• A- = 62, A. = 63
• BA = 64, BB = 65, et ainsi de suite, jusqu'à BZ = 89.
• Ba = 90, Bb = 91, et ainsi de suite, jusqu'à Bz = 115.
• B0 = 116, B1 = 117, et ainsi de suite, jusqu'à B9 = 125.
• B- = 126, B. = 127
• 9A = 3 904, 9B = 3 905, et ainsi de suite, jusqu'à 9Z = 3 929
• 9a = 3930, 9b = 3931, et ainsi de suite, jusqu'à 9z = 3 955
• 90 = 3956, 91 = 3957, et ainsi de suite, jusqu'à 99 = 3965
• 9- = 3966, 9. = 3967
• -A = 3968, -B = 3969, et ainsi de suite, jusqu'à -Z = 3993
• -a = 3994, -b = 3995, et ainsi de suite, jusqu'à -z = 4 019.
• -0 = 4 020, -1 = 4 021, et ainsi de suite, jusqu'à -9 = 4 029.
• -- = 4030, -. = 4031
• .A = 4 032, .B = 4 033, et ainsi de suite, jusqu'à .Z = 4 057.
• .a = 4 058, .b = 4 059, et ainsi de suite, jusqu'à .z = 4 083.
• .0 = 4 084, .1 = 4 085, et ainsi de suite, jusqu'à .9 = 4 093.
• .- = 4094, .. = 4095

Vous pouvez utiliser l'outil suivant pour encoder une valeur unique, ou le code JavaScript pour mettre à l'échelle et encoder une chaîne d'URL complète.

Exemple :

Équivaut à la chaîne encodée au format texte chd=t:90,1000,2700,3500|3968,-1,1100,250.

chd=e:BaPoqM2s,-A__RMD6

Haut de page

Mise à l'échelle des données et de l'axe

Les données sont mises à l'échelle pour s'adapter à votre graphique, de manière explicite (lorsque vous utilisez un format de texte avec un scaling personnalisé) ou implicitement (tous les autres types). Cela signifie que chaque graphique est mis à l'échelle pour s'adapter à la plage disponible du format, et non à la plage réelle des données que vous fournissez.

Vous pouvez être amené à mettre à l'échelle vos données de sorte qu'elles couvrent toute la plage de valeurs autorisées par votre format, afin de rendre les différences plus évidentes. Vous pouvez mettre à l'échelle vos données soit en les adaptant au format que vous utilisez, soit en spécifiant explicitement la plage de données (c'est-à-dire en utilisant le format texte avec un scaling personnalisé).

Notez que les valeurs des libellés des axes sont calculées sur une échelle entièrement indépendante et n'ont rien à voir avec les valeurs des données. Vous devez toutefois utiliser la plage par défaut (0 à 100). Vous pouvez toutefois modifier cette plage.

Cette section décrit ces deux problèmes.

Les données sont mises à l'échelle pour s'adapter à la plage de formats [Tous les graphiques, sauf à secteurs et Venn]

Différents formats sont compatibles avec différentes plages de valeurs. Vos données sont mises à l'échelle en fonction de la plage de votre format, de sorte que la valeur maximale acceptée par votre format s'affiche en haut de cet axe, et la valeur minimale pour votre format en bas. Les exemples suivants montrent la même valeur (100) avec un format de texte de base (plage 0 à 100), du texte avec une mise à l'échelle personnalisée (plage personnalisée de 0 à 200) et un format d'encodage étendu (plage 0 à 4095).

Format de texte de base	Format de texte avec mise à l'échelle personnalisée	Format d'encodage étendu
Valeur: 100 (chd=t:100) Plage de formats: 0 – 100 Le chiffre 100 correspond à 100/100 sur l'échelle.	Valeur 100 (chd=t:100, chds=0,200) Plage de formats: 0 – 200 La valeur 100 est affichée à 100/200 sur l'échelle.	Valeur: 100 (chd=e:Bk) Plage de formats: de 0 à 4 095 Le chiffre 100 s'affiche sous la forme 100/4 095 sur l'échelle.

Un moyen simple de mettre à l'échelle vos données pour les adapter à votre graphique consiste à utiliser le format texte avec mise à l'échelle. Une méthode plus complexe consiste à mettre à l'échelle manuellement vos données afin qu'elles correspondent à la plage acceptée par votre format.

Graphiques à secteurs et de Venn: avec les graphiques à secteurs et de Venn, toutes les valeurs sont l'une par rapport à l'autre, et non par rapport à l'échelle totale du graphique.

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

La plage des libellés de l'axe est calculée indépendamment [Barre, Ligne, Radar, Nuage de points et Chandelier]

Vous pouvez choisir d'afficher les valeurs des axes à l'aide du paramètre chxt. Toutefois, il est important de noter que les libellés des axes ne sont pas calculés pour refléter les données du graphique, mais sont calculés indépendamment par l'API ou spécifiés explicitement par vous.

La plage par défaut de l'axe est comprise entre 0 et 100, indépendamment des valeurs des données ou de leur mise à l'échelle. Par exemple, si vous affichez l'axe des y à l'aide des libellés d'axe par défaut sur un graphique utilisant un encodage étendu (plage de 0 à 4 095), les libellés de l'axe y afficheront toujours entre 0 et 100, sauf si vous modifiez cela explicitement, comme expliqué ci-dessous. Voici un exemple illustrant les étiquettes par défaut de l'axe des ordonnées dans un graphique à barres d'encodage étendu avec une valeur de données de 100:

chd=e:Bk (équivalent à chd=t:100)

Toutefois, vous pouvez spécifier la plage de l'axe à l'aide du paramètre chxr. Si vous souhaitez que les valeurs des axes reflètent des valeurs de données réelles, vous devez spécifier des valeurs minimale et maximale d'axe correspondant à la plage de formats que vous utilisez. Notez que le format de texte de base a déjà une échelle de 0 à 100. Par conséquent, si vous l'utilisez (sans mise à l'échelle personnalisée), les valeurs des axes correspondront aux valeurs des données par défaut. Prenons quelques exemples pour illustrer cela. Voici trois graphiques contenant les mêmes données (15,26,51,61), mais des formats et des échelles d'axe différentes:

Encodage simple, aucune mise à l'échelle d'axe	Encodage simple, axe ajusté	Texte de base, aucune mise à l'échelle d'axe
chd=s:Paz9   Plage de valeurs d'encodage simple: 0 – 61 Plage par défaut de l'axe (0–100) La plage d'encodage est inférieure à la plage de l'axe du libellé. Par conséquent, les barres ne correspondent pas à la valeur réelle sur le libellé de l'axe. Cependant, les barres sont correctement proportionnées les unes par rapport aux autres.	chd=s:Paz9     chxr=0,0,61,10 Plage de valeurs d'encodage simple: 0 – 61 La plage de l'axe est explicitement définie sur 0-61 La plage d'encodage et la plage de l'axe sont égales. Les barres correspondent donc à leur valeur correcte sur l'axe.	chd=t:15,26,51,61   Plage de valeurs du format texte de base: 0 à 100 Plage par défaut de l'axe (0–100) La plage d'encodage et la plage de l'axe sont à nouveau identiques. Par conséquent, les valeurs de données précises sont affichées sur l'axe, par défaut. Étant donné que la plage de formats de texte est plus grande que celle du format d'encodage simple (100 unités contre 61 unités), les barres sont plus petites ici que dans les autres graphiques, mais tous les graphiques restent proportionnés les uns par rapport aux autres.

Haut de page

Script d'encodage JavaScript

Pour une utilisation réelle, il est probablement plus facile d'encoder des données de manière automatisée plutôt que manuellement.

L'extrait de code JavaScript suivant encode une seule série en encodage simple ou extended, et met à l'échelle les valeurs de données pour qu'elles correspondent à la plage complète de cet encodage. Les données doivent être fournies sous forme de tableau de nombres positifs. Toute valeur fournie qui n'est pas un nombre positif est encodée en tant que valeur manquante à l'aide du trait de soulignement (_).

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

Pour encoder des données, appelez la fonction simpleEncode ou extendedEncode, en transmettant le tableau contenant vos données (valueArray) et la valeur maximale de vos données (maxValue). Pour créer de l'espace entre la valeur la plus élevée et le haut du graphique, définissez maxValue de sorte qu'il soit supérieur au plus grand nombre du tableau de données, comme suit:

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

Haut de page