Formati di dati

Questo documento spiega come inviare i dati dei tuoi grafici all'API di Google Chart.

Indice

Panoramica

I dati relativi a quasi tutti i grafici vengono inviati utilizzando il parametro chd. I dati devono essere inviati in uno dei seguenti formati:

• Il formato di testo di base è essenzialmente costituito da numeri in virgola mobile semplici compresi tra 0 e 100 inclusi. Si tratta di un formato facile da leggere e scrivere a mano.
• Il formato di testo con scalabilità automatica scala il grafico per adattarsi ai tuoi dati.
• Il formato di testo con scalabilità personalizzata è simile al formato di testo di base, ma consente di specificare un intervallo personalizzato utilizzando un secondo parametro URL.
• Il formato di codifica semplice consente di specificare valori interi compresi tra 0 e 61 inclusi, codificati da un singolo carattere alfanumerico. Questa codifica genera la stringa di dati più corta tra tutti i formati di dati (se i valori sono maggiori di 9).
• Il formato di codifica esteso consente di specificare valori interi compresi tra 0 e 4095 inclusi, codificati da due caratteri alfanumerici. La codifica estesa è più adatta a un grafico con molti dati e un ampio intervallo di dati.

I valori dei dati vengono scalati per adattarsi al formato utilizzato; consulta Scalabilità dei dati e scalabilità degli assi per una spiegazione di come i dati vengono manipolati per adattarli al grafico.

Forniamo uno snippet JavaScript per la codifica dei dati in formati di codifica semplice o di codifica estesa. In alternativa, diversi membri del gruppo di Grafici di Google hanno contribuito con altre librerie per contribuire alla formattazione: effettua una ricerca negli archivi per trovarli.

Formato testo di base

I dati con formattazione di testo di base consentono di specificare valori in virgola mobile compresi tra 0 e 100 inclusi come numeri. I valori inferiori a 0 sono contrassegnati come mancanti. I valori superiori a 100 vengono troncati a 100. Il vantaggio del formato di testo di base è che i valori sono facili da leggere e comprensibili nell'URL e le etichette dell'asse predefinite mostrano i valori dei dati in modo accurato. Tuttavia, la formattazione del testo (semplice o con parametri personalizzati) genera la stringa di dati più lunga di tutti i formati.

Se i tuoi dati includono valori al di fuori dell'intervallo specificato per la formattazione del testo, puoi scalare i dati convertendoli in percentuali del valore più grande nei tuoi dati. In alternativa, puoi utilizzare la formattazione del testo con scalabilità personalizzata per gestire il ridimensionamento per te.

Sintassi:

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

<data>

Ogni serie contiene uno o più valori separati da virgole. Separa più serie utilizzando una barra verticale (|). I valori sono numeri in virgola mobile compresi tra 0 e 100 inclusi. I valori minori di zero o il trattino basso ( _) sono considerati valori nulli. I valori superiori a 100 vengono troncati a 100.

 

Esempio:

Una tabella con cinque valori. Il trattino basso è considerato un valore nullo, il valore -30 è inferiore al valore minimo e viene quindi eliminato e il valore 200 viene troncato a 100.

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

Torna all'inizio

Formato del testo con scalabilità automatica

Puoi configurare alcuni grafici per scalare automaticamente per adattarli ai relativi dati. Il grafico verrà scalato in modo che il valore più grande si trovi in alto e il più piccolo (o zero, se tutti i valori sono maggiori di zero) sia in basso.

Tutti i valori degli indicatori mostrati nel grafico mostreranno i valori effettivi, non quelli in scala.

Questa funzionalità è valida solo per i valori in formato testo e non funziona con tutti i tipi di grafici. Fai delle prove con il tipo di grafico che preferisci per vedere se è supportato.

Sintassi

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

Esempi:

chd=t:5,30,50,80,200 chds=a Tieni presente che il grafico a torta non deve utilizzare valori < 0 per i grafici a torta.

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

Torna all'inizio

Formato di testo con scalabilità personalizzata

Il formato di testo con scalabilità personalizzata consente di specificare numeri arbitrarie in virgola mobile o positivi, in combinazione con un parametro di scalabilità che consente di specificare un intervallo personalizzato per il grafico. Questo grafico è utile quando non vuoi preoccuparti di limitare i dati a un intervallo specifico o non vuoi scalare i dati manualmente per adattarli perfettamente a un grafico. Questo formato modificherà automaticamente la linea dello zero, se necessario. Il formato dei dati è lo stesso del formato di testo di base.

Per la scalabilità automatica, specifica chds=a.

La formattazione del testo (semplice o con parametri personalizzati) genera la stringa di dati più lunga di tutti i formati.

Sintassi:

La formattazione del testo con scalabilità personalizzata richiede due parametri:

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

chd=t:<data>

Uguale al formato dei dati normali: uno o più valori separati da virgole per serie, più serie separate da una barra verticale (|). L'intervallo di valori consentiti in ogni serie è specificato dal parametro chds.

chds

Un insieme di uno o più valori minimo e massimo consentiti per ogni serie di dati, separati da virgole. Devi specificare sia un valore massimo che uno minimo. Se fornisci meno coppie rispetto al numero di serie di dati, l'ultima coppia viene applicata a tutte le serie di dati rimanenti. Tieni presente che ciò non modifica l'intervallo dell'asse; per modificarlo, devi impostare il parametro chxr. I valori validi sono compresi tra (+/-)9,999e(+/-)199. Puoi specificare i valori in notazione standard o E.

<series_1_min>

Il valore minimo consentito nella prima serie. I valori più bassi sono contrassegnati come mancanti.

<series_1_max>

Valore massimo consentito nella prima serie. I valori più alti vengono troncati a questo valore.

 

Esempio:

Un grafico a barre con una scala min/max compresa tra -80 e 140. I valori 30, -60, 50, 140 e 80 rientrano nella scala, pertanto non vengono troncati. Tieni presente che la linea dello zero viene regolata automaticamente, ossia 80/(140 + 80) = 0,36 fino all'alto dell'asse y. Tieni inoltre presente che l'intervallo predefinito dell'asse Y è ancora compreso tra 0 e 100, nonostante il parametro chds, per cui i valori dell'etichetta non riflettono i valori effettivi dei dati.

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

Torna all'inizio

Formato di codifica semplice

Il formato di codifica semplice consente di specificare valori interi compresi tra 0 e 61 inclusi, codificati da un singolo carattere alfanumerico. In questo modo si ottiene l'URL della stringa di dati più breve tra tutti i formati di dati. Tuttavia, se disponi di un grafico a linee o a barre più lungo di 100 pixel lungo l'asse dei dati, ti consigliamo di utilizzare un altro formato. Questo perché, con solo 62 valori di dati supportati, la granularità dei dati è molto maggiore di quella di visualizzazione e i valori saranno solo leggermente diversi (non molto, ma visibili su grafici più grandi).

Tieni presente che se utilizzi il parametro chds con una codifica semplice, le dimensioni degli elementi dei dati sul grafico non saranno interessate, mentre i valori degli indicatori del punto dati verranno modificati.

Sintassi:

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

<serie_1>

Una stringa in cui ogni carattere è un singolo punto dati e le serie sono delimitate da una virgola. I singoli valori all'interno di una serie non sono delimitati. Di seguito sono riportati i caratteri di dati supportati e i relativi valori:

• A—Z, dove A = 0, B = 1 e così via, per Z = 25
• a—z, dove a = 26, b = 27 e così via, per z = 51
• 0(zero)—9, dove 0 = 52 e 9 = 61
• Il trattino basso (_) indica un valore mancante

Puoi utilizzare il seguente strumento per codificare un singolo valore oppure il codice JavaScript per scalare e codificare un'intera stringa URL.

Esempio:

Equivalente alla stringa con codifica testo chd=t:1,19,27,53,61,-1|12,39,57,45,51,27

<xtitle="chs=320x200&cht=bvs&chd=s:btb19_,mn5tzb&chco=ffcc33,ffe9a4&chxr=0,0,61,5&chxt=y" alt="Grafico a barre in pila con due serie e sei valori ciascuno, codifica semplice.chd=s:BTb19_,Mn5tzb src="/static/chart_image/image</chd

Torna all'inizio

Formato di codifica esteso

Il formato di codifica esteso consente di specificare valori interi compresi tra 0 e 4095 inclusi, codificati da due caratteri alfanumerici. Utilizza una sintassi leggermente diversa rispetto a quella semplice.

Tieni presente che se utilizzi il parametro chds con una codifica semplice, le dimensioni degli elementi dei dati sul grafico non saranno interessate, mentre i valori degli indicatori del punto di dati verranno modificati.

Sintassi:

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

<serie_1>

Una stringa in cui ogni due caratteri rappresenta un singolo punto dati e le serie sono delimitate da una virgola. I singoli valori di una serie non sono delimitati. Ecco i caratteri di codifica supportati:

• A—Z
• a—z
• 0—9
• punto (.)
• Trattino (-)
• I valori mancanti sono indicati con un doppio trattino basso (__).

Di seguito è riportata una breve descrizione dei valori codificati:

• AA = 0, AB = 1 e così via fino a AZ = 25
• Aa = 26, Ab = 27 e così via fino a Az = 51
• A0 = 52, A1 = 53 e così via fino a A9 = 61
• A- = 62, A. = 63
• BA = 64, BB = 65 e così via fino a BZ = 89
• Ba = 90, Bb = 91 e così via fino a Bz = 115
• B0 = 116, B1 = 117 e così via fino a B9 = 125
• B- = 126, B. = 127
• 9A = 3904, 9B = 3905 e così via fino a 9Z = 3929
• 9a = 3930, 9b = 3931 e così via fino a 9z = 3955
• 90 = 3956, 91 = 3957 e così via fino a 99 = 3965
• 9- = 3966, 9. = 3967
• -A = 3968, -B = 3969 e così via fino a -Z = 3993
• -a = 3994, -b = 3995 e così via fino a -z = 4019
• -0 = 4020, -1 = 4021 e così via fino a -9 = 4029
• -- = 4030, -. = 4031
• .A = 4032, .B = 4033 e così via fino a .Z = 4057
• .a = 4058, .b = 4059 e così via fino a .z = 4083
• .0 = 4084, .1 = 4085 e così via fino a .9 = 4093
• .- = 4094, .. = 4095

Puoi utilizzare il seguente strumento per codificare un singolo valore oppure il codice JavaScript per scalare e codificare un'intera stringa URL.

Esempio:

Equivalente alla stringa con codifica testo chd=t:90,1000,2700,3500|3968,-1,1100,250

chd=e:BaPoqM2s,-A__RMD6

Torna all'inizio

Scalabilità dei dati e scalabilità degli assi

I dati vengono ridimensionati per adattarsi al grafico in modo esplicito (quando utilizzi il formato di testo con scalabilità personalizzata) o implicitamente (tutti gli altri tipi). Ciò significa che ogni grafico viene ridimensionato per adattarsi all'intervallo disponibile del formato, non all'intervallo effettivo dei dati forniti.

Ti consigliamo di scalare i dati in modo che coprono l'intero intervallo di valori consentiti dal tuo formato, per rendere le differenze più evidenti. Puoi scalare i dati scalandoli per adattarli al formato che utilizzi oppure specificando esplicitamente l'intervallo di dati (ovvero utilizzando il formato di testo con la scalabilità personalizzata).

Tieni presente che i valori delle etichette dell'asse vengono calcolati su una scala completamente indipendente e non hanno nulla a che fare con i valori dei dati, ma viene utilizzato l'intervallo predefinito compreso tra 0 e 100. Tuttavia, puoi modificare questo intervallo.

Questa sezione descrive entrambi i problemi.

I dati vengono scalati per adattarsi all'intervallo di formato [Tutti i grafici tranne Pie e Venn]

Formati diversi supportano intervalli di valori diversi. I dati vengono adattati all'intervallo di formato, in modo che il valore massimo supportato dal formato venga visualizzato nella parte superiore dell'asse, mentre il valore minimo per il formato viene visualizzato in basso. I seguenti esempi mostrano lo stesso valore (100) utilizzando il formato di testo di base (intervallo 0-100), testo con scalabilità personalizzata (intervallo personalizzato da 0 a 200) e il formato di codifica esteso (intervallo 0-4095).

Formato testo di base	Formato di testo con scalabilità personalizzata	Formato di codifica esteso
Valore: 100 (chd=t:100) Intervallo formato: 0-100 Il 100 viene reso come 100/100 nella scala.	Valore 100 (chd=t:100, chds=0,200) Intervallo formato: 0-200 Il 100 viene reso 100/200 in alto.	Valore: 100 (chd=e:Bk) Intervallo formato: 0-4095 Il 100 viene reso come 100/4095 dalla scala.

Un modo semplice per scalare i dati per adattarli al grafico è utilizzare il formato di testo con scalabilità. Un metodo più complesso consiste nel scalare manualmente i dati per adattarli all'intervallo supportato dal tuo formato.

Grafici a torta e di Venn: nei grafici a torta e di Venn, tutti i valori sono relativi tra loro e non alla scala totale del grafico.

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

L'intervallo delle etichette dell'asse viene calcolato in modo indipendente [a barre, a linee, radar, a dispersione e a candele]

Puoi scegliere di visualizzare i valori dell'asse utilizzando il parametro chxt. Tuttavia, è importante notare che le etichette degli assi non vengono calcolate per riflettere i dati del grafico, ma vengono calcolate in modo indipendente dall'API o specificate esplicitamente da te.

L'intervallo predefinito dell'asse è 0-100, indipendentemente dai valori o dalla scalabilità dei dati. Quindi, ad esempio, se visualizzi l'asse y con le etichette predefinite dell'asse su un grafico che utilizza la codifica estesa (intervallo 0-4095), le etichette dell'asse y continueranno a leggere 0-100 a meno che non lo modifichi in modo esplicito, come spiegato di seguito. Ecco un esempio che mostra le etichette predefinite dell'asse Y in un grafico a barre di codifica estesa con un valore dei dati pari a 100:

chd=e:Bk (equivalente a chd=t:100)

Tuttavia, puoi specificare l'intervallo dell'asse utilizzando il parametro chxr. Se vuoi che i valori dell'asse riflettano i valori effettivi dei dati, devi specificare i valori minimo e massimo dell'asse che corrispondano al tuo intervallo di formato. Tieni presente che il formato di testo di base ha già una scala da 0 a 100, quindi se utilizzi la formattazione di testo di base (senza scalabilità personalizzata), per impostazione predefinita i valori dell'asse corrisponderanno ai valori dei dati. Vediamo come funziona con alcuni esempi. Ecco tre grafici con gli stessi dati (15,26,51,61), ma formati diversi e scale di assi diversi:

Codifica semplice, nessuna scalabilità dell'asse	codifica semplice, asse scalato	Testo di base, nessuna scala dell'asse
chd=s:Paz9   Intervallo di valori di codifica semplice: 0-61 Intervallo asse predefinito (0-100) L'intervallo di codifica è inferiore a quello dell'asse delle etichette, quindi le barre non corrispondono al valore effettivo sull'etichetta dell'asse. Tuttavia, le barre sono proporzionate tra loro in modo adeguato.	chd=s:Paz9     chxr=0,0,61,10 Intervallo di valori di codifica semplice: 0-61 Intervallo asse impostato esplicitamente su 0-61 L'intervallo di codifica e l'intervallo dell'asse sono uguali, quindi le barre corrispondono al loro valore corretto sull'asse.	chd=t:15,26,51,61   Intervallo di valori del formato di testo di base: 0-100 Intervallo asse predefinito (0-100) L'intervallo di codifica e l'intervallo dell'asse sono di nuovo gli stessi, quindi per impostazione predefinita vengono mostrati i valori precisi dei dati sull'asse. Poiché l'intervallo del formato del testo è più ampio dell'intervallo del formato di codifica semplice (100 unità rispetto a 61 unità), le barre sono più piccole rispetto agli altri grafici, ma tutti i grafici rimangono proporzionali tra loro.

Torna all'inizio

Script di codifica JavaScript

Per l'uso reale, probabilmente è più facile codificare i dati in modo programmatico anziché manualmente.

Il seguente snippet di JavaScript codifica una singola serie in una codifica semplice o extended e ridimensiona i valori dei dati per adattarli all'intervallo completo della codifica. I dati devono essere forniti come un array di numeri positivi. Qualsiasi valore che non sia un numero positivo viene codificato come valore mancante utilizzando il trattino basso (_).

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

Per codificare i dati, chiama la funzione simpleEncode o extendedEncode, passando l'array che contiene i dati (valueArray) e il valore massimo dei dati (maxValue). Per creare uno spazio tra il valore più alto e la parte superiore del grafico, imposta maxValue in modo che sia maggiore del numero più grande nell'array di dati, come segue:

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

Torna all'inizio