Formats de données

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

Sommaire

  1. Présentation
  2. Format texte de base
  3. Format du texte avec scaling automatique
  4. Format du texte avec autoscaling
  5. Format d'encodage simple
  6. Extended Encodage Format (Format d'encodage étendu)
  7. Scaling des données et scaling de l'axe
  8. Script d'encodage JavaScript

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 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 redimensionne le graphique en fonction de vos données.
  • Le format de texte avec mise à l'échelle personnalisée est semblable au format texte de base, mais il vous permet de spécifier une plage personnalisée à l'aide d'un second paramètre d'URL.
  • Le format d'encodage simple vous 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 permet d'obtenir la chaîne de données la plus courte de tous les formats de données (si des 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 aux graphiques contenant beaucoup de données et une grande plage de données.

Les valeurs des données sont mises à l'échelle pour s'adapter au format utilisé. Consultez la section Mise à l'échelle des données et mise à l'échelle de l'axe pour découvrir comment les données sont manipulées pour s'adapter au graphique.

Nous fournissons un extrait JavaScript pour encoder des données dans des formats d'encodage simples ou étendus. Plusieurs membres du groupe Google Charts ont également ajouté d'autres bibliothèques pour faciliter la mise en forme : effectuez des recherches dans les archives pour les trouver.

Format 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 texte de base est que les valeurs sont faciles à lire et à comprendre dans l'URL, et que les libellés d'axe par défaut affichent les valeurs avec précision. Toutefois, 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 de tous les formats.

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

Syntaxe:

chd=t:val,val,val|val,val,val...
<data>
Chaque série est constituée 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 trait de soulignement ( _) sont considérées comme des valeurs nulles. Les valeurs supérieures à 100 sont tronquées à 100.

 

Exemple :

Un tableau à 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. Graphique à barres à 5 valeurs, encodage de texte.
chd=t:_,30,-30,50,80,200

Haut de page

Format de texte avec scaling automatique

Vous pouvez configurer certains graphiques pour qu'ils s'adaptent automatiquement à leurs données. Le graphique est mis à l'échelle de sorte que la plus grande valeur soit en haut et la plus petite (ou zéro, si toutes les valeurs sont supérieures à zéro) apparaît en bas.

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

Cette fonctionnalité n'est compatible qu'avec les valeurs au format texte et pas avec tous les types de graphiques. Testez différents types de graphiques pour vérifier s'il est compatible.

Syntaxe

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

Exemples :


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

Notez que les graphiques à secteurs ne doivent pas utiliser de valeurs inférieures à 0.

 Graphique à barres à 5 valeurs, encodage de texte.
chd=t:-5,30,-30,50,80,200
chds=a

Haut de page

Format du texte avec ajustement personnalisé

Le format texte avec mise à l'échelle personnalisée vous permet de spécifier des nombres arbitraires à virgule flottante positifs ou négatifs, 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 vous soucier de limiter vos données à une plage spécifique ou si vous ne souhaitez pas mettre à l'échelle manuellement les données pour qu'elles tiennent parfaitement dans un graphique. Ce format ajuste la ligne zéro si nécessaire. Le format des données est identique à celui du 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 de tous les formats.

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 bruts: 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 les plus élevées 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 pour vous, à savoir 80/(140 + 80) = 0,36 vers le haut de l'axe des 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. Par conséquent, les valeurs des étiquettes ne reflètent pas les valeurs réelles des données.

 Graphique à barres à 5 valeurs, encodage du texte avec mise à l&#39;échelle des données.

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

Haut de page

Format d'encodage simple

Un format d'encodage simple vous permet de spécifier des valeurs entières comprises entre 0 et 61 inclusifs, encodées par un seul caractère alphanumérique. Cela correspond à l'URL de chaîne de données la plus courte de tous les formats de données. Toutefois, si l'axe de données de votre graphique en courbes ou à barres fait plus de 100 pixels de long, 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 grande que celle de l'affichage. De plus, les valeurs sont légèrement décalées (pas grand-chose, mais visibles sur les graphiques plus grands).

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 ne sera pas affectée, mais les valeurs des repères de données le seront.

Syntaxe:

chd=s:
  <series_1>
    ,...,
  <series_n>
<series_1>
Chaîne, où 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 seule valeur, ou le code JavaScript pour mettre à l'échelle et encoder une chaîne d'URL entière.

Exemple :

Équivalent à 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 chacune, encodage simple." src="/ch5chart_0&title=10.
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, encodées par deux caractères alphanumériques. La syntaxe utilisée est légèrement différente de l'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 ne sera pas affectée, mais les valeurs des repères de point de données le seront.

Syntaxe :

chd=e:
  <series_1>
    ,...,
  <series_n>
<série_1>
Chaîne où chacun des deux caractères représente un seul point de données, et où 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
  • point (.)
  • tiret (-)
  • Les valeurs manquantes sont signalées par un double trait de soulignement (__).

Voici une version 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 = 3 930, 9b = 3 931, et ainsi de suite jusqu'à 9z = 3 955
  • 90 = 3 956, 91 = 3 957, et ainsi de suite jusqu'à 99 = 3 965
  • 9- = 3966, 9. = 3967
  • -A = 3 968, -B = 3 969, et ainsi de suite jusqu'à -Z = 3 993
  • -a = 3 994, -b = 3 995, 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 seule valeur, ou le code JavaScript pour mettre à l'échelle et encoder une chaîne d'URL entière.

Exemple :

Équivalent à la chaîne encodée au format texte chd=t:90,1000,2700,3500|3968,-1,1100,250 Graphique à barres empilées avec deux séries de quatre valeurs chacune, encodage étendu.
chd=e:BaPoqM2s,-A__RMD6

Haut de page

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

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

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. 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 (en d'autres termes, utiliser 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 de données. Elles utilisent la plage par défaut de 0 à 100. Cependant, vous pouvez 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 Pie et Venn]

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

Format texte de base Format texte avec autoscaling Format d'encodage étendu
Graphique à barres avec texte de base avec mise à l&#39;échelle personnalisée

Valeur: 100 (chd=t:100)

Plage de formats: 0 à 100

La valeur 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 nombre 100 correspond à 100/4 095 sur l'échelle.

Un moyen simple d'adapter les données à votre graphique consiste à utiliser le format de texte avec mise à l'échelle. Une méthode plus complexe consiste à effectuer un scaling manuel de 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 relatives les unes par rapport aux autres, 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 [à barres, en courbes, en radar, à nuage de points et en chandeliers japonais]

Vous pouvez choisir d'afficher les valeurs des axes à l'aide du paramètre chxt. Cependant, 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 soit calculés indépendamment par l'API, soit spécifiés explicitement par vous.

La plage des axes par défaut est comprise entre 0 et 100, indépendamment des valeurs ou de l'échelle des données. Par exemple, si vous affichez l'axe des ordonnées à l'aide des libellés d'axe par défaut sur un graphique utilisant un encodage étendu (plage de 0 à 4 095), ces libellés afficheront toujours la valeur 0 à 100, sauf si vous modifiez cela explicitement, comme expliqué ci-dessous. Voici un exemple montrant les libellés 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 les valeurs de données réelles, vous devez spécifier les valeurs minimale et maximale des axes qui correspondent à la plage de votre format. Notez que le format de texte de base comporte déjà une échelle de 0 à 100. Par conséquent, si vous utilisez la mise en forme de texte de base (sans mise à l'échelle personnalisée), les valeurs de l'axe correspondront par défaut aux valeurs des données. 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, mise à l'échelle de l'axe Encodage simple, axe mis à l'échelle Texte de base, aucune mise à l'échelle de l'axe

chd=s:Paz9
 

Plage de valeurs d'encodage simple: 0–61

Plage des axes par défaut (0 à 100)

La plage d'encodage étant plus petite que celle de l'axe du libellé, les barres ne correspondent pas à la valeur réelle sur l'étiquette 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

Plage d'axe explicitement définie sur 0 à 61

La plage d'encodage et la plage des axes 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 des axes par défaut (0 à 100)

La plage d'encodage et la plage des axes étant à nouveau identiques, les valeurs de données précises sont affichées sur l'axe par défaut.

Étant donné que la plage de format de texte est plus étendue que celle du format d'encodage simple (100 unités au lieu de 61 unités), les barres sont plus petites ici que dans les autres graphiques, mais tous les graphiques restent proportionnels les uns par rapport aux autres.

Haut de page

Script d'encodage JavaScript

Dans la pratique, il est probablement plus facile d'encoder les données de manière automatisée que manuellement.

L'extrait de code JavaScript suivant encode une série unique en utilisant un encodage simple ou extended, et adapte les valeurs de données pour qu'elles correspondent à la gamme complète de cet encodage. Les données doivent être fournies sous la forme d'un tableau de nombres positifs. Toute valeur fournie autre qu'un nombre positif est encodée en tant que valeur manquante en utilisant le 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 un espace entre la valeur la plus élevée et le haut du graphique, définissez maxValue sur une valeur supérieure 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