Esta página descreve os princípios básicos de como usar a API de gráficos do Google para fazer gráficos.
Política de uso da API de gráficos do Google
Não há limite para o número de chamadas por dia que você pode fazer para a API de gráficos do Google. No entanto, nos reservamos o direito de bloquear qualquer uso que considerarmos abusivo.
Informações gerais
Como ver os gráficos nesta documentação
Todas as imagens de gráficos nesta documentação são geradas em tempo real usando a API de gráficos do Google. Para ver o URL de qualquer imagem:
- Se estiver usando o Firefox, clique com o botão direito do mouse e selecione "Exibir imagem" ou "Propriedades".
- Se estiver usando o Internet Explorer, clique com o botão direito do mouse e selecione "Propriedades".
Para facilitar a leitura dos URLs, este documento com frequência os exibe em mais de uma linha. Quando você estiver usando a API de gráficos do Google, deve fornecer o URL em uma linha.
A API de gráficos do Google retorna uma imagem de gráfico em resposta a uma solicitação de URL GET ou POST. A API pode gerar muitos tipos de gráficos, desde gráficos de pizza ou de linhas até códigos QR e fórmulas. Todas as informações sobre o gráfico que você quer, como dados, tamanho, cores e rótulos dele fazem parte do URL. Para solicitações POST, é um pouco diferente, mas não se preocupe com isso agora.
Para tornar o gráfico mais simples possível, seu URL só precisa especificar o tipo, os dados e o tamanho do gráfico. Você pode digitar esse URL diretamente no
navegador ou apontar para ele com uma tag <img>
na página da Web. Por exemplo, siga este link para ver um gráfico de setores:
https://chart.googleapis.com/chart?chs=250x100&chd=t:60,40&cht=p3&chl=Hello|World
O link anterior é um exemplo de URL básico da API de gráficos do Google. Todos os URLs de gráficos têm o seguinte formato:
https://chart.googleapis.com/chart?cht=<chart_type>&chd=<chart_data>&chs=<chart_size>&...additional_parameters...
Todos os URLs começam com https://chart.googleapis.com/chart? seguido pelos parâmetros que especificam os dados e o visual do gráfico. Os parâmetros são pares de name=value, separados por um "e" comercial (&), e podem estar em qualquer ordem, depois do ?. Todos os gráficos exigem, no mínimo, os seguintes parâmetros: cht (tipo de gráfico), chd (dados) e chs (tamanho do gráfico). No entanto, há muitos outros parâmetros para opções adicionais, e você pode especificar quantos parâmetros adicionais forem aceitos pelo gráfico.
Vamos examinar o URL acima em mais detalhes:
| URL | Componentes |
|---|---|
|
|
Copie e cole esse URL no navegador e tente fazer algumas alterações: adicione outros valores aos dados (não se esqueça de colocar uma vírgula antes de cada novo valor de dados). Adicione
novos rótulos (coloque uma marca | antes de cada novo valor). Aumente o gráfico.
Como criar um gráfico
Veja como criar um gráfico de imagem:
- Escolha um tipo de gráfico. Acesse a galeria para ver uma lista de gráficos. O tipo de gráfico é especificado pelo parâmetro
cht. Faça um esboço de todos os componentes que você quer que o gráfico tenha (eixos, rótulos, planos de fundo etc.) e, se necessário, descubra as dimensões em pixels dos vários componentes (tamanho total do gráfico, tamanho da legenda etc.). Primeiro, leia a documentação com atenção para selecionar seu tipo de gráfico. Caso contrário, sua experiência pode ser frustrante. - Crie e formate os dados do gráfico. Os dados são especificados usando o parâmetro
chd. Você precisa decidir qual formato usar para seus dados:- Escolha um formato de dados. Use o formato de texto simples para os dados do gráfico, que é fácil de ler, mas ocupa mais espaço para enviar, ou use um dos tipos de codificação, que é menor, mas restringe o intervalo de valores possíveis.
- Decida se os dados precisam ser dimensionados para se ajustarem ao seu gráfico. Formatos diferentes aceitam intervalos de valores distintos. É possível dimensionar os dados para que eles incluam o intervalo completo de valores permitidos pelo seu formato para tornar as diferenças mais óbvias. Faça isso dimensionando os dados para que se ajustem ao formato de dados que você usa ou usando a formatação de texto com dimensionamento personalizado.
- Codifique seus dados, se necessário. Se você escolheu um formato codificado, oferecemos um pouco de JavaScript para ajudar com outros tipos de codificação.
- Especifique o tamanho do gráfico. O tamanho do gráfico é especificado usando o parâmetro
chs. Consulte a documentação sobre o formato e os valores máximos. - Adicione outros parâmetros. A documentação de cada gráfico lista os parâmetros opcionais disponíveis. As opções típicas incluem rótulos, títulos e
cores. Todos os textos de rótulos ou títulos devem ser codificados em UTF-8. Muitos
parâmetros permitem inserir diversos valores. Por exemplo, o parâmetro
chmpermite colocar uma forma em um único ponto de dados em um gráfico. Você pode colocar formas em vários pontos de dados usando o parâmetrochm. No entanto, para isso, não especifique o parâmetrochmvárias vezes no URL (por exemplo, WRONG:chm=square&chm=circle&chm=triangle). Em vez disso, os parâmetros que aceitam diversos valores usam um delimitador, como uma vírgula ou barra vertical, entre diversos valores no mesmo parâmetro. Parachm, é uma barra, então o resultado vai ser RIGHT:chm=square|circle|triangle. Consulte os detalhes de cada parâmetro para saber como especificar diversos parâmetros. - Crie a string do seu URL. O URL começa com
https://chart.googleapis.com/chart?e é seguido por todos os parâmetros obrigatórios (cht,chd,chs) e opcionais. Observação:se você estiver usando seu URL em uma tag<img>, será necessário mudar todos os caracteres¶&no link. Exemplo:<img src="https://chart.googleapis.com/chart?chs=250x100&chd=t:60,40&cht=p3&chl=Hello|World" />. - Use GET ou POST para encontrar sua imagem. GET é quando você digita o URL diretamente no navegador ou o usa em uma tag
<img>. No entanto, os URLs são limitados a 2.000 caracteres. Portanto, se você tiver mais dados do que isso ou gostar de sangue, considere usar o método POST, como descrito aqui. - Crie regiões clicáveis. Também é possível criar um mapa de imagem para o gráfico e adicionar hiperlinks ou clicar em elementos a elementos específicos. Consulte Como criar um mapa de imagem de gráfico para mais detalhes.
Glossário de termos de gráficos
Veja alguns termos importantes que usamos nesta documentação:
- Série
- Um conjunto de dados relacionados em um gráfico.
O que constitui uma série depende do tipo de gráfico: em um gráfico de linhas, uma série é uma única linha; em um gráfico de pizza, cada entrada é uma fatia, e todas as fatias juntas são uma série. Em um gráfico de barras, uma série consiste em todas as barras do mesmo conjunto de dados. As séries diferentes são agrupadas lado a lado ou empilhadas umas sobre as outras, dependendo do tipo de gráfico. O gráfico a seguir demonstra
um gráfico de barras agrupadas com duas séries, uma em azul escuro e outra em azul-claro:
- Rótulos do eixo
- Valores numéricos ou de texto ao longo de cada
eixo. No gráfico anterior, seriam os rótulos "Jan", "Fev," "Mar", "0", "50", "100".
Componentes do gráfico
Veja alguns componentes de um gráfico:
- Área do gráfico
- A área que mostra a arte da série. Consulte a barra lateral "Componentes do gráfico" para mais detalhes.
- Legenda
- Uma pequena área no gráfico que descreve a série. No gráfico acima, é a seção que lista "Gatos" e "Cachorros".
- Parâmetro
- Um par key=value usado no URL. Por exemplo:
chxt=x, em quechxté o nome do parâmetro exé o valor do parâmetro. - GET e POST
- Dois métodos de enviar o URL do gráfico. O GET geralmente é feito digitando um URL no navegador ou tornando-o a origem de uma tag
<img>. As solicitações POST são mais complexas, mas podem incluir muito mais dados. O principal motivo para usar POST em vez de GET é que uma solicitação POST pode consumir muito mais dados do que uma GET (16 mil caracteres em comparação a 2 mil caracteres). Abordamos o POST aqui. - Caractere barra vertical
- O caractere
|, geralmente usado como um delimitador de valor de parâmetro, ou seja, um caractere para quebrar vários valores. Vírgulas e "e" comercial (&) também são usados como delimitadores no URL do gráfico. - Gráficos compostos
- Um gráfico que combina dois tipos diferentes de gráfico: por exemplo, um gráfico de barras com uma linha ou um gráfico de linhas com marcadores de vela. Consulte Gráficos compostos.
Otimizações
Agora que você aprendeu os princípios básicos de como criar um gráfico, veja algumas otimizações que podem ser usadas.
Como usar o POST
Os URLs têm um limite de 2.000 caracteres. Portanto, se o gráfico tiver mais dados do que isso, você precisará usar POST em vez de GET, conforme descrito aqui. GET é quando você digita o URL do gráfico na barra de URL do navegador ou o usa como fonte de um elemento <img> em uma página da Web. O POST requer programação adicional em outra linguagem, como PHP ou PERL.
Como ciar gráficos em JavaScript
Você pode usar a API Google Visualization para criar gráficos de imagem. A API Google Visualization é baseada em JavaScript. Ela oferece ferramentas para criar, filtrar e manipular dados ou consultar planilhas do Google ou outros sites em busca de dados. Você pode usar a API de visualização para criar seus dados e, em seguida, fazer com que ela chame a API de gráficos de imagem para renderizar o gráfico na página. Para mais informações, consulte a documentação do gráfico de imagem genérico ou, na galeria de visualização, veja se há gráficos do Google marcados (imagem).