Formatos de dados

Este documento explica como enviar os dados do seu gráfico para a API de gráficos do Google.

Sumário

1. Visão geral
2. Formato de texto básico
3. Formato de texto com dimensionamento automático
4. Formato de texto com dimensionamento personalizado
5. Formato de codificação simples
6. Formato de codificação estendida
7. Escalonamento de dados e de eixos
8. Script de codificação JavaScript

Informações gerais

Os dados de quase todos os gráficos são enviados usando o parâmetro chd. Os dados precisam ser enviados em um dos seguintes formatos:

• O formato de texto básico são basicamente números de ponto flutuante simples de 0 a 100. Esse formato é fácil de ler e escrever à mão.
• O formato de texto com escalonamento automático ajusta o gráfico aos seus dados.
• O formato de texto com dimensionamento personalizado é semelhante ao formato de texto básico, mas permite especificar um intervalo personalizado usando um segundo parâmetro de URL.
• O formato de codificação simples permite especificar valores inteiros de 0 a 61, inclusive, codificados por um único caractere alfanumérico. Essa codificação resulta na string de dados mais curta de qualquer um dos formatos de dados (se houver valores maiores que 9).
• O formato de codificação estendida permite especificar valores inteiros de 0 a 4095, codificados por dois caracteres alfanuméricos. A codificação estendida é mais adequada para um gráfico com muitos dados e um grande intervalo de dados.

Os valores dos dados são dimensionados para se ajustar ao formato usado. Consulte Escalonamento de dados e eixos para uma explicação de como os dados são manipulados para se ajustarem ao gráfico.

Fornecemos um snippet JavaScript para codificação de dados em formatos simples ou estendidos. Como alternativa, vários membros do grupo do Gráficos Google contribuíram com outras bibliotecas para ajudar na formatação: pesquise nos arquivos para encontrá-los.

Formato de texto básico

Os dados básicos em formato de texto permitem especificar valores de ponto flutuante de 0 a 100, inclusive, como números. Os valores abaixo de zero são marcados como ausentes. Os valores acima de 100 são truncados para 100. A vantagem do formato de texto básico é que os valores são fáceis de ler e entender no URL, e os rótulos do eixo padrão mostram os valores dos dados com precisão. No entanto, a formatação de texto (seja simples ou com parâmetros personalizados) resulta na string de dados mais longa de todos os formatos.

Se os dados incluírem valores fora do intervalo especificado para a formatação de texto, você poderá dimensionar os dados convertendo-os em porcentagens do maior valor dos dados. Como alternativa, use a formatação de texto com dimensionamento personalizado para processar o dimensionamento para você.

Sintaxe:

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

<data>

Cada série tem um ou mais valores separados por vírgula. Separe várias séries usando uma barra vertical (|). Os valores são números de ponto flutuante de 0 a 100. Valores menores que zero ou o caractere sublinhado ( _ ) são considerados valores nulos. Os valores maiores que 100 são truncados para 100.

 

Exemplo:

Uma tabela com cinco valores. O sublinhado é considerado um valor nulo, o valor -30 fica abaixo do valor mínimo e, por isso, é descartado, e o valor 200 é truncado para 100.

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

Voltar ao início

Formato de texto com dimensionamento automático

Alguns gráficos podem ser escalonados automaticamente de acordo com os dados deles. O gráfico será dimensionado de modo que o maior valor esteja na parte superior e o menor (ou zero, se todos os valores forem maiores que zero) na parte inferior.

Todos os valores de marcador mostrados no gráfico vão mostrar os valores reais, não os dimensionados.

Esse recurso funciona apenas com valores em formato de texto e não funciona com todos os tipos de gráficos. Teste seu tipo de gráfico para ver se ele é compatível.

Sintaxe

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

Exemplos:

chd=t:5,30,50,80,200 chds=a Observe que você não deve usar valores < 0 para gráficos de pizza.

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

Voltar ao início

Formato de texto com dimensionamento personalizado

O formato de texto com dimensionamento personalizado permite especificar números de ponto flutuante positivos ou negativos arbitrários, em combinação com um parâmetro de dimensionamento que permite especificar um intervalo personalizado para o gráfico. Esse gráfico é útil quando você não quer se preocupar em limitar os dados a um intervalo específico ou não quer escalonar os dados manualmente para caberem bem dentro de um gráfico. Esse formato ajusta a linha zero conforme necessário. O formato dos dados é o mesmo do formato de texto básico.

Para escalonamento automático, especifique chds=a.

A formatação de texto (seja simples ou com parâmetros personalizados) resulta na string de dados mais longa de todos os formatos.

Sintaxe:

O formato de texto com dimensionamento personalizado requer dois parâmetros:

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

chd=t:<data>

Igual ao formato de dados simples: um ou mais valores separados por vírgula por série e várias séries separadas por uma barra vertical (|). O intervalo dos valores permitidos em cada série é especificado pelo parâmetro chds.

chds

Um conjunto de um ou mais valores mínimos e máximos permitidos para cada série de dados, separados por vírgulas. É preciso fornecer um valor máximo e um mínimo. Se você fornecer menos pares do que séries de dados, o último par será aplicado a todas as séries de dados restantes. Observe que isso não muda o intervalo do eixo. Para mudar o intervalo do eixo, é necessário definir o parâmetro chxr. Os valores válidos vão de (+/-) 9,999e(+/-) 199. Você pode especificar os valores em padrão ou na notação E.

<series_1_min>

O valor mínimo permitido na primeira série. Os valores inferiores são marcados como ausentes.

<series_1_max>

Valor máximo permitido na primeira série. Valores mais altos são truncados para esse valor.

 

Exemplo:

Um gráfico de barras com escala mínima/máxima de -80 a 140. Os valores 30, -60, 50, 140 e 80 se enquadram na escala, portanto, não são truncados. A linha zero é ajustada automaticamente, 80/(140 + 80) = 0,36 do eixo y. O intervalo padrão do eixo y ainda é de 0 a 100, apesar do parâmetro chds. Portanto, os valores do rótulo não refletem os valores reais dos dados.

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

Voltar ao início

Formato de codificação simples

O formato de codificação simples permite especificar valores inteiros de 0 a 61, codificados por um único caractere alfanumérico. Isso resulta no URL de string de dados mais curto de todos os formatos de dados. No entanto, se você tiver um gráfico de linhas ou barras com mais de 100 pixels ao longo do eixo de dados, convém usar outro formato. Isso acontece porque, com apenas 62 valores de dados compatíveis, a granularidade dos dados é muito maior do que a granularidade da exibição, e os valores serão um pouco deslocados (não muito, mas visível em gráficos maiores).

Se você usar o parâmetro chds com codificação simples, o tamanho do elemento de dados no gráfico não será afetado, mas os valores de marcador de ponto de dados serão.

Sintaxe:

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

<série_1>

Uma string em que cada caractere é um ponto de dados único e as séries são delimitadas por vírgulas. Os valores individuais de uma série não são separados. Confira os caracteres de dados aceitos e os valores correspondentes:

• A—Z, em que A = 0, B = 1 e assim por diante, até Z = 25
• a—z, em que a = 26, b = 27 e assim por diante, até z = 51
• 0(zero)—9, em que 0 = 52 e 9 = 61
• O caractere sublinhado (_) indica um valor ausente

Use a ferramenta a seguir para codificar um único valor ou o código JavaScript para dimensionar e codificar uma string de URL inteira.

Exemplo:

Equivalente à string codificada em texto 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="Gráfico de barras empilhadas com duas séries e seis valores cada, codificação simples." src="/static/chart/imagem." chd=s:BTb19_,Mn5tzb

Voltar ao início

Formato de codificação estendida

O formato de codificação estendida permite especificar valores inteiros de 0 a 4.095, codificados por dois caracteres alfanuméricos. A sintaxe é um pouco diferente da codificação simples.

Se você usar o parâmetro chds com codificação simples, o tamanho do elemento de dados no gráfico não será afetado, mas os valores de marcador de ponto de dados serão.

Sintaxe:

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

<série_1>

Uma string em que cada dois caracteres são um único ponto de dados e as séries são delimitadas por vírgulas. Os valores individuais da mesma série não são separados. Confira os caracteres de codificação aceitos:

• A—Z
• a—z
• 0—9
• período (.)
• hífen (-)
• Os valores ausentes são indicados com um sublinhado duplo (__).

Veja a seguir uma descrição abreviada dos valores codificados:

• AA = 0, AB = 1 e assim por diante até AZ = 25
• Aa = 26, Ab = 27 e assim por diante até Az = 51
• A0 = 52, A1 = 53 e assim por diante até A9 = 61
• A- = 62, A. = 63
• BA = 64, BB = 65 e assim por diante até BZ = 89
• Ba = 90, Bb = 91 e assim por diante até Bz = 115
• B0 = 116, B1 = 117 e assim por diante até B9 = 125
• B- = 126, B. = 127
• 9A = 3.904, 9B = 3.905 e assim por diante até 9Z = 3.929
• 9a = 3.930, 9b = 3.931 e assim por diante até 9z = 3.955
• 90 = 3.956, 91 = 3.957 e assim por diante até 99 = 3.965
• 9- = 3.966, 9. = 3.967
• -A = 3.968, -B = 3.969 e assim por diante até -Z = 3.993
• -a = 3.994, -b = 3.995 e assim por diante até -z = 4019.
• -0 = 4020, -1 = 4021 e assim por diante até -9 = 4029
• -- = 4.030, -. = 4.031
• .A = 4032, .B = 4033 e assim por diante até .Z = 4057
• .a = 4.058, .b = 4.059 e assim por diante até .z = 4.083
• .0 = 4084, .1 = 4085 e assim por diante até .9 = 4093
• .- = 4.094, .. = 4.095

Use a ferramenta a seguir para codificar um único valor ou o código JavaScript para dimensionar e codificar uma string de URL inteira.

Exemplo:

Equivalente à string codificada em texto chd=t:90,1000,2700,3500|3968,-1,1100,250

chd=e:BaPoqM2s,-A__RMD6

Voltar ao início

Escalonamento de dados e de eixos

Os dados são dimensionados para se ajustarem ao gráfico de forma explícita (ao usar formato de texto com dimensionamento personalizado) ou implicitamente (todos os outros tipos). Isso significa que cada gráfico é dimensionado para se ajustar ao intervalo disponível do formato, não ao intervalo real dos dados fornecidos.

É possível dimensionar seus dados para que eles incluam o intervalo completo de valores permitidos pelo seu formato para tornar as diferenças mais óbvias. É possível dimensionar seus dados dimensionando-os para que se ajustem ao formato usado ou especificando explicitamente o intervalo de dados (ou seja, use o formato de texto com dimensionamento personalizado).

Observe que os valores dos rótulos dos eixos são calculados em uma escala completamente independente e não têm nada a ver com os valores de dados, mas usam o intervalo padrão de 0 a 100. Entretanto, você pode alterar esse intervalo.

Esta seção descreve as duas questões.

Os dados são dimensionados para se ajustarem ao intervalo de formato [Todos os gráficos, exceto os de pizza e Venn]

Os diferentes formatos suportam diferentes intervalos de valores. Os dados são dimensionados de acordo com o intervalo de formatos. Assim, o valor máximo aceito pelo formato é renderizado na parte superior do eixo e o valor mínimo para o formato é renderizado na parte inferior. Os exemplos a seguir mostram o mesmo valor (100) usando formato de texto básico (intervalo de 0 a 100), texto com dimensionamento personalizado (intervalo personalizado de 0 a 200) e formato de codificação estendido (intervalo de 0 a 4095).

Formato de texto básico	Formato de texto com dimensionamento personalizado	Formato de codificação estendida
Valor: 100 (chd=t:100) Intervalo do formato: 0 a 100 O 100 é renderizado 100/100 escala acima.	Valor 100 (chd=t:100, chds=0,200) Intervalo do formato: 0 a 200 O 100 é renderizado 100/200 escala acima.	Valor: 100 (chd=e:Bk) Intervalo do formato: 0 a 4095 O 100 é renderizado como 100/4095 escala acima.

Uma maneira fácil de dimensionar seus dados para que se ajustem ao gráfico é usar o formato de texto com dimensionamento. Um método mais complexo é escalonar manualmente os dados para que se ajustem ao intervalo compatível com seu formato.

Gráficos de pizza e Venn: nos gráficos de pizza e Venn, todos os valores são relativos entre si, não à escala total do gráfico.

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

O intervalo dos rótulos dos eixos é calculado de maneira independente [barras, linhas, radar, dispersão e candlestick]

É possível mostrar os valores de eixo usando o parâmetro chxt. No entanto, é importante observar que os rótulos dos eixos não são calculados para refletir os dados do gráfico, mas são calculados de forma independente pela API ou especificados explicitamente por você.

O intervalo do eixo padrão é de 0 a 100, independentemente dos valores ou do dimensionamento dos dados. Por exemplo, se você exibir o eixo y usando rótulos padrão em um gráfico que usa codificação estendida (intervalo de 0 a 4095), os rótulos do eixo y ainda lerão de 0 a 100, a menos que você altere isso explicitamente, conforme explicado abaixo. Veja um exemplo que mostra os rótulos padrão do eixo y em um gráfico de barras de codificação estendida com um valor de dados de 100:

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

No entanto, você pode especificar o intervalo do eixo usando o parâmetro chxr. Se quiser que os valores dos eixos reflitam os valores reais dos dados, especifique os valores mínimo e máximo do eixo que correspondem ao intervalo do formato. Observe que o formato de texto básico já tem uma escala de 0 a 100. Portanto, se você estiver usando a formatação básica de texto (sem dimensionamento personalizado), os valores do eixo corresponderão aos valores dos dados por padrão. Vamos ilustrar isso com alguns exemplos. Veja três gráficos com os mesmos dados (15,26,51,61), mas formatos e dimensionamentos de eixo diferentes:

Codificação simples, sem dimensionamento dos eixos	Codificação simples, com dimensionamento dos eixos	Texto básico, sem dimensionamento dos eixos
chd=s:Paz9   Intervalo de valores de codificação simples: 0 a 61 Intervalo do eixo padrão (0 a 100) O intervalo de codificação é menor que o intervalo do eixo do rótulo, portanto, as barras não correspondem ao valor real no rótulo do eixo. No entanto, as barras são proporcionais umas às outras.	chd=s:Paz9     chxr=0,0,61,10 Intervalo de valores de codificação simples: 0 a 61 Intervalo do eixo definido explicitamente como 0 a 61 O intervalo de codificação e o intervalo do eixo são iguais, então as barras correspondem ao valor correto no eixo.	chd=t:15,26,51,61   Intervalo de valores no formato de texto básico: 0 a 100 Intervalo do eixo padrão (0 a 100) O intervalo de codificação e o intervalo do eixo são novamente iguais. Portanto, os valores de dados precisos são mostrados no eixo, por padrão. Como o intervalo de formato de texto é maior do que o intervalo de formato de codificação simples (100 unidades versus 61 unidades), as barras são menores aqui do que nos outros gráficos, mas todos os gráficos permanecem proporcionais uns aos outros.

Voltar ao início

Script de codificação JavaScript

Para uso real, provavelmente é mais fácil codificar os dados de maneira programática em vez de manualmente.

O snippet de JavaScript a seguir codifica uma série em codificação simples ou extended e dimensiona os valores de dados para se ajustarem ao intervalo completo dessa codificação. Os dados precisam ser fornecidos como uma matriz de números positivos. Qualquer valor fornecido que não seja um número positivo é codificado como um valor ausente usando o caractere sublinhado (_).

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

Para codificar dados, chame a função simpleEncode ou extendedEncode, transmitindo a matriz que contém os dados (valueArray) e o valor máximo deles (maxValue). Para criar um espaço entre o valor mais alto e o topo do gráfico, defina maxValue para ser maior que o maior número na matriz de dados, da seguinte maneira:

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

Voltar ao início