Warning: This API is deprecated in 2012 and was turned off on March 18, 2019. Please use the actively maintained Google Charts API instead.

Formatos de dados

Stay organized with collections Save and categorize content based on your preferences.

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

Sumário

Visão geral

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 básico de texto é essencialmente simples números de ponto flutuante de 0 a 100. Esse formato é fácil de ler e gravar manualmente.
  • O formato de texto com escalonamento automático dimensiona o gráfico para caber nos seus dados.
  • O formato de texto com escalonamento 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 algum valor for maior que 9).
  • O formato de codificação estendida permite que você especifique valores inteiros de 0 a 4.095, inclusive, codificados por dois caracteres alfanuméricos. A codificação estendida é mais adequada para um gráfico com muitos dados e um intervalo de dados grande.

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

Fornecemos um snippet de JavaScript para codificar dados em formatos de codificação simples ou estendidos. Vários membros do grupo do Google Chart contribuíram com outras bibliotecas para ajudar na formatação: pesquise os arquivos para encontrá-los.

Formato de texto básico

Dados básicos formatados em texto permitem especificar valores de ponto flutuante de 0 a 100, inclusive números. Valores abaixo de zero são marcados como ausentes. 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 dos eixos padrão mostram os valores de 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 formatação de texto, será possível convertê-los convertendo-os em porcentagens do maior valor nos dados. Como alternativa, é possível usar a formatação de texto com escalonamento personalizado para processar o escalonamento automaticamente.

Sintaxe:

chd=t:val,val,val|val,val,val...
<dados>
Cada série é um ou mais valores separados por vírgulas. Separe várias séries usando uma barra vertical (|). Os valores são números de pontos flutuantes de 0 a 100, inclusive. 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. Gráfico de barras com cinco valores, codificação de texto.
chd=t:_,30,-30,50,80,200

Voltar ao início

Formato de texto com escalonamento automático

Você pode configurar alguns gráficos para que escalonem automaticamente de acordo com os dados. O gráfico será dimensionado para que o maior valor fique na parte superior do gráfico e o menor (ou zero, se todos os valores forem maiores que zero) na parte inferior.

Os valores de marcador exibidos no gráfico exibirão os valores reais, não os valores ajustados.

Esse recurso funciona apenas com valores formatados de texto e não funciona com todos os tipos de gráficos. Teste o 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

A pizza não deve usar valores abaixo de 0 nos gráficos de pizza.

Gráfico de barras com cinco valores, codificação de texto.
chd=t:-5,30,-30,50,80,200
chds=a

Voltar ao início

Formato de texto com escalonamento personalizado

Com o formato de texto com escalonamento personalizado, é possível especificar números de pontos flutuantes positivos ou negativos arbitrários em combinação com um parâmetro de escalonamento que permite especificar um intervalo personalizado para o gráfico. Este gráfico é útil quando você não quer se preocupar em limitar seus dados a um intervalo específico ou não quer dimensionar os dados manualmente para caber bem em 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:<dados>
Assim como o formato de dados simples: um ou mais valores separados por vírgula por série, várias séries separadas por um caractere de barra vertical (|). O intervalo de 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. Forneça um máximo e um mínimo. Se você fornecer menos pares do que as séries de dados, o último par será aplicado a todas as séries de dados restantes. Isso não muda o intervalo do eixo. Para alterar o intervalo do eixo, é necessário definir o parâmetro chxr. Os valores válidos variam de (+/-)9,999e(+/-)199. Você pode especificar valores em notação padrão ou E.
<série_1_min>
O valor mínimo permitido na primeira série. Os valores menores são marcados como ausentes.
<série_1_máx>
Valor máximo permitido na primeira série. Valores maiores 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, eles não são truncados. A linha zero é ajustada para você, 80/(140 + 80) = 0,36 do caminho até o eixo y.

Observe também que 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 de dados.

Gráfico de barras com cinco valores, codificação de texto com dimensionamento de 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, inclusive, codificados por um único caractere alfanumérico. Isso resulta no URL da string de dados mais curto de todos os formatos de dados. No entanto, se você tem um gráfico de linhas ou barras com mais de 100 pixels ao longo do eixo de dados, recomendamos usar outro formato. Isso porque, com apenas 62 valores de dados compatíveis, a granularidade dos dados é muito maior que a granularidade da tela, e os valores serão um pouco desativados (não muito, mas visíveis 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 do marcador de ponto de dados serão.

Sintaxe:

chd=s:
  <series_1>
    ,...,
  <series_n>
<série_1>
Uma string, em que cada caractere é um único ponto de dados, e as séries são delimitadas por vírgula. Os valores individuais de uma série não são separados. Veja os caracteres de dados compatíveis 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 de sublinhado (_) indica um valor ausente

Você pode usar a seguinte ferramenta para codificar um único valor ou o código JavaScript para escalonar 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 Gráfico de barras empilhadas com duas séries e seis valores cada, com codificação simples.
chd=s:BTb19_,Mn5tzb

Voltar ao início

Formato de codificação estendida

O formato de codificação estendida permite que você especifique valores inteiros de 0 a 4.095, inclusive, codificados por dois caracteres alfanuméricos. Ela usa uma 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 do marcador de ponto de dados serão.

Sintaxe:

chd=e:
  <series_1>
    ,...,
  <series_n>
<série_1>
Uma string em que cada dois caracteres é um único ponto de dados, e as séries são delimitadas por uma vírgula. Os valores individuais da mesma série não são separados. Veja os caracteres de codificação compatíveis:
  • A—Z
  • a—z
  • 0—9
  • (.)
  • 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 para AZ = 25
  • Aa = 26, Ab = 27 e assim por diante para Az = 51
  • A0 = 52, A1 = 53 e assim por diante para 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 para Bz = 115
  • B0 = 116, B1 = 117 e assim por diante para 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 para 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 = 3994, -b = 3995 e assim por diante para -z = 4019
  • -0 = 4020, -1 = 4021 e assim por diante para -9 = 4029
  • -- = 4.030, -. = 4.031
  • .A = 4032, .B = 4033 e assim por diante para .Z = 4057
  • .a = 4058, .b = 4059 e assim por diante para .z = 4083
  • .0 = 4084, .1 = 4085 e assim por diante para .9 = 4093
  • .- = 4.094, .. = 4.095

Você pode usar a seguinte ferramenta para codificar um único valor ou o código JavaScript para escalonar e codificar uma string de URL inteira.

Exemplo:

Equivalente à string codificada em texto chd=t:90,1000,2700,3500|3968,-1,1100,250 Gráfico de barras empilhadas com duas séries de quatro valores cada, com codificação estendida.
chd=e:BaPoqM2s,-A__RMD6

Voltar ao início

Escalonamento de dados e eixos

Os dados são ajustados para caber no gráfico, explicitamente (ao usar o formato de texto com escalonamento personalizado) ou implicitamente (todos os outros tipos). Isso significa que cada gráfico é dimensionado para se ajustar ao intervalo disponível do formato, e não ao intervalo real dos dados que você fornece.

Talvez você queira escalonar os dados para que eles incluam todo o intervalo de valores permitido pelo formato, para tornar as diferenças mais óbvias. É possível ajustar os 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 escalonamento personalizado).

Os valores do rótulo do eixo 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 ajustados para se ajustarem ao intervalo dos formatos [Todos os gráficos, exceto Pie e Venn]

Os diferentes formatos suportam diferentes intervalos de valores. Os dados são dimensionados para o intervalo de formatos, de modo que o valor máximo compatível com o formato seja renderizado na parte superior do eixo e o valor mínimo para o formato seja renderizado na parte inferior. Os exemplos a seguir mostram o mesmo valor (100) usando o formato de texto básico (intervalo de 0 a 100), texto com escalonamento 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
Gráfico de barras no formato de texto básico com dimensionamento personalizado

Valor: 100 (chd=t:100)

Intervalo de formato: 0 a 100

O 100 é renderizado 100/100 escala acima.

Valor 100 (chd=t:100, chds=0,200)

Intervalo de formato: 0 a 200

O 100 é renderizado 100/200 escala acima.

Valor: 100 (chd=e:Bk)

Intervalo de formato: 0 a 4095

O 100 é renderizado como 100/4095 escala acima.

Uma maneira fácil de ajustar os dados para que se ajustem ao gráfico é usar o formato de texto com escalonamento. Um método mais envolvido é escalonar manualmente os dados para ajustá-los ao intervalo compatível com o formato.

Gráficos de pizza e Venn: com os 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 do eixo é calculado de forma independente [Barra, Linha, Radar, Dispersão e Vela]

É possível exibir os valores dos eixos usando o parâmetro chxt. No entanto, é importante observar que os rótulos de 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 escalonamento de dados. Por exemplo, se você exibir o eixo y usando os rótulos de eixo padrão em um gráfico que usa codificação estendida (intervalo de 0 a 4095), os rótulos do eixo y ainda vão ler de 0 a 100, a menos que você mude explicitamente, como explicado abaixo. Veja um exemplo que mostra as etiquetas 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, é possível especificar o intervalo do eixo usando o parâmetro chxr. Se você quiser que os valores dos eixos reflitam os valores de dados reais, especifique os valores mínimo e máximo do eixo que correspondam ao seu intervalo de formato. 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 escalonamento personalizado), os valores dos eixos corresponderão aos valores de dados por padrão. Vamos ilustrar isso com alguns exemplos. Veja abaixo três gráficos com os mesmos dados (15,26,51,61), mas formatos e escalas de eixo distintos:

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 simples de valor de codificação: 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. Por isso, as barras não correspondem ao valor real no rótulo do eixo. No entanto, as barras são proporcionadas corretamente entre si.

chd=s:Paz9
    chxr=0,0,61,10

Intervalo simples de valor de codificação: 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. Portanto, as barras correspondem ao valor correto no eixo.

chd=t:15,26,51,61
 

Intervalo de valor do 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. Por isso, os valores de dados precisos são mostrados no eixo, por padrão.

Como o intervalo do formato de texto é maior do que o intervalo de formato de codificação simples (100 unidades vs. 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 dados de maneira programática do que manualmente.

O snippet de JavaScript a seguir codifica uma única série em codificação simples ou estendida e escalona os valores de dados para que se ajustem a todo o intervalo 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 os dados, chame a função simpleEncode ou extendedEncode, transmitindo a matriz que contém os dados (valueArray) e o valor máximo dos dados (maxValue). Para criar espaço entre o valor mais alto e a parte superior 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