Descrição da interface a ser utilizada para extração de dados do Banco Sidra

Introdução

A interface é implementada através de um serviço HTTP Web API, no estilo REST, que é invocado pela construção de uma URL, cujos parâmetros definem a tabela multidimensional Sidra de onde os dados serão extraídos, e quais dados de cada dimensão são necessários.

O enfoque principal é que esta possa ser utilizada de forma simples nos programas clientes (inclusive em dispositivos móveis), de modo a permitir a criação de aplicações dinâmicas que consumam os dados vindos do Banco Sidra no formato JSON.

A URL a ser utilizada possui uma parte constante, que referencia o programa que irá analisar os parâmetros e fornecer os valores, e de uma parte variável, com os parâmetros que definem a tabela Sidra e que valores recuperar em cada uma de suas dimensões, separados por barras (/).
Além destes, também existem alguns parâmetros que definem a formatação dos dados recebidos.

Parte constante da URL: http://api.sidra.ibge.gov.br/values

Parte variável da URL: uma sequência de /<tipo de parâmetro>/<valor do parâmetro>

Tipos de parâmetro para extração de dados:

Os diferentes tipos de parâmetro definem a tabela e suas dimensões (períodos, variáveis, unidades territoriais e classificações/categorias) a serem consultadas.
Os parâmetros que definem as unidades territoriais podem ser utilizados mais de uma vez, permitindo a consulta de unidades territoriais de níveis territoriais distintos.
Os parâmetros que definem as classificações/categorias variam de acordo com a tabela, até um máximo de 6.
Portanto, uma tabela Sidra pode ter no máximo 9 dimensões: 3 dimensões obrigatórias (períodos, variáveis e unidades territoriais) e até 6 classificações/categorias.


t – para especificar o código da tabela de onde se deseja extrair os dados.

Exemplo: /t/1612


p – para especificar os períodos (meses, anos etc.) desejados.

Caso não especificado o parâmetro p, o valor default é last (/p/last, vide abaixo).

Os períodos podem ser especificados de forma avulsa, separados por vírgula (,), em faixas, separados por traço (-), ou de ambas as formas
Um período pode ter o formato AAAA, de 4 dígitos, que representa um ano, ou o formato AAAADD, de 6 dígitos, onde AAAA representa um ano e DD seu correspondente mês (01 a 12), trimestre (01 a 04), semestre (01 a 02), etc, de acordo com a periodicidade de divulgação dos dados da tabela.

Exemplo 1: /p/2008,2010-2012 – especifica os anos de 2008, e 2010 a 2012.

Exemplo 2: /p/201101-201112,201204,201208 – especifica os meses de janeiro a dezembro de 2012, abril de 2012 e agosto de 2012.

O parâmetro p pode ser seguido pela constante all para especificar todos os períodos disponíveis.

Exemplo 3: /p/all

O parâmetro p pode ser seguido pela constante first e um número de períodos, indicando os primeiros períodos da lista de períodos disponíveis (períodos mais antigos).
O número de períodos pode ser omitido quando se tratar de apenas um aperíodo.

Exemplo 4: /p/first 12

Exemplo 5: /p/first

O parâmetro p pode ser seguido pela constante last e um número de períodos, indicando os últimos períodos da série (períodos mais recentes).
O número de períodos pode ser omitido quando se tratar de apenas um período.

Exemplo 6: /p/last 12

Exemplo 7: /p/last (valor default, quando não especificado o parâmetro p)


v – para especificar as variáveis desejadas.

Caso não especificado o parâmetro v, o valor default é allxp (/v/allxp, vide abaixo).

As variáveis são especificadas através de seus códigos, separados por vírgula (,).
A lista de variáveis pode incluir também as variáveis de percentual geradas automaticamente pelo Sidra (são variáveis cujos códigos são superiores a 1.000.000).

Exemplo 1: /v/63,69 – especifica o percentual no mês e o percentual acumulado no ano do IPCA.

O parâmetro v pode ser seguido pela constante all para especificar todas as variáveis da tabela, inclusive as variáveis de percentual geradas automaticamente pelo Sidra.

Exemplo 2: /v/all

O parâmetro v pode ser seguido pela constante allxp para especificar todas as variáveis da tabela, exceto as variáveis de percentual geradas automaticamente pelo Sidra.

Exemplo 3: /v/allxp (valor default, quando não especificado o parâmetro v)


n<nível territorial> – para especificar os níveis territoriais e suas unidades territoriais desejadas.

Pode ser especificado mais de uma vez, para informar unidades territoriais de níveis distintos.

<nível territorial> informa o código de um dos níveis territoriais onde existem dados disponíveis para a tabela.
Como exemplos, temos n1 – Brasil, n2 – Grande Região, n3 – Unidade da Federação, n6 – Município, etc.

As unidades territoriais são especificadas através de seus códigos IBGE, separadas por vírgula (,).

Exemplo 1: /n6/3304557,3550308 – especifica os municípios do Rio de Janeiro e São Paulo.

O parâmetro n<nível territorial> pode ser seguido pela constante all para especificar todas as unidades territoriais disponíveis na tabela.

Exemplo 2: /n6/all – especifica todos os municípios.

O parâmetro n<nível territorial> pode ser seguido pela constante in seguida por n<nível territorial superior> e <códigos IBGE de unidades territoriais superiores, separados por vírgula (,)> para especificar todas as unidades territoriais contidas em unidades territoriais superiores de um nível territorial superior.

Exemplo 3: /n6/in n3 11,12 - especifica os municípios contidos nas Unidades da Federação Rondônia e Acre.

Exemplo 4: /n3/in n2 3,4 – especifica as Unidades da Federação contidas nas Grandes Regiões Sudeste e Sul.

Exemplo 5: /n1/1/n2/1/n3/in n2 1 – especifica Brasil (n1/1) seguido pela Grande Região Norte (n2/1) e pelas Unidades da Federação contidas na Grandes Região Norte.

Caso se deseje especificar códigos de unidades territoriais extintas (ex: UFs Fernando de Noronha - 20 e Guanabara - 34), como em /n3/20,34/, deve-se acrescentar na lista de parâmetros, em qualqer posição, o parâmetro /u/y, que informa que devem ser consideradas as unidades territoriais extintas. O valor default deste parâmetro é /u/n, o que faz com que não sejam aceitos os código de unidades territoriais extintas.
Uma outra função do parâmetro /u/y é considerar as unidades territoriais extintas (desde que a tabela possua os seus dados) nas listas de unidades territoriais do resultado, como em /n3/in n2 3/, que listaria as UFs da Grande Região Sudeste, inclusive a extinta UF Guanabara, como também em /n3/all, que listaria todas as UFs, inclusive as extintas Guanabara e Fernando de Noronha.


c<classificação> – para especificar as classificações da tabela e suas categorias desejadas.

Se alguma das classificações da tabela for omitida, será assumida para ela a categoria que representa o total.
Se esta categoria não existir na classificação, a consulta retornará os valores com o símbolo que indica que os dados não se aplicam (.., vide ao final).

<classificação> informa o código de uma das classificações da tabela.
Como exemplos, temos c1 – Situação do domicílio, c2 – Sexo, c81 – Produto da lavoura temporária, etc.

As categorias são especificadas através de seus códigos, de forma individual ou para compor uma soma, separadas por vírgula (,).
As categorias que compõem a soma devem ser separadas por espaço.

Exemplo 1: /c81/2692,2702,2694 2695 – especifica os produtos da lavoura temporária arroz, feijão e (batata doce + batata inglesa)

O parâmetro c<classificação> pode ser seguido pela constante all para especificar todas as categorias disponíveis, inclusive a categoria que representa o total.

Exemplo 2: /c81/all – especifica todos os produtos da lavoura temporária

O parâmetro c<classificação> pode ser seguido pela constante allxt para especificar todas as categorias disponíveis, exceto a categoria que representa o total.

Exemplo 3: /c81/allxt – especifica todos os produtos da lavoura temporária, exceto a categoria que representa o total.



Tipos de parâmetro para formatação de dados:

Além dos parâmetros para extração de dados anteriormente citados existem alguns parâmetros que permitem definir como os dados em formato JSON recebidos serão formatados.


f – para especificar a formatação do resultado, i.e., que tipo de descritor de cada uma das dimensões da tabela comporá o resultado recebido.
Cada um dos diferentes descritores (metadados) permite identificar um valor recebido.

Especifique /f/c para receber apenas os códigos dos descritores.
Especifique /f/n para receber apenas os nomes dos descritores.
Especifique /f/u para receber o código e o nome das unidades terrritoriais consultadas e o nome dos demais descritores.
Especifique /f/a para receber os códigos e os nomes dos descritores (valor default, caso o parâmetro f não seja especificado).


d – para especificar com quantas casas decimais serão formatados os valores.

Especifique /d/s para formatar os valores com o nro. de casas decimais padrão definido pelo Sidra para cada variável (valor default, caso o parâmetro d não seja especificado).
Especifique /d/m para formatar os valores com o nro. de casas decimais máximo disponível para cada variável (maior precisão).
Especifique /d/0 a /d/9 para formatar os valores com um nro. fixo de casas decimais, entre 0 e 9.


h – para especificar se o resultado recebido será precedido por um registro de cabeçalho (header).
O registro de header permite identificar o código e/ou o nome de cada uma das dimensões da tabela que compõem o resultado recebido.

Especifique /h/y para receber o header (valor default, caso o parâmetro h não seja especificado).
Especifique /h/n para não receber o header.


A estrutura dos dados recebidos

Os dados são recebidos no formato JSON, onde cada registro possui os códigos e/ou os nomes dos descritores do valor em cada dimensão, o código e/ou o nome da unidade de medida, e o próprio valor.
Além destes, caso tenha havido a seleção de unidades territoriais de diferentes níveis territoriais (como no exemplo 5 da descrição do parâmetro n<nível territorial> acima), o registro possuirá em seu início o código e/ou o nome do nível territorial, para que se saiba para cada unidade territorial consultada a que nível pertence.

Os campos de nível territorial são nomeados pela letra N, seguida pela letra C, que identifica um código de nível territorial, ou N, que identifica um nome de nível territorial.
Ex: NC, NN

Os campos de descritor são nomeados pela letra D, seguida de um dígito de 1 a 9 que identifica a dimensão, e seguida pela letra C, que identifica um código de descritor, ou N, que identifica um nome de descritor.
Ex: D1C, D1N, D2C, D2N etc.

Os campos de unidade de medida são nomeados pela letra M, seguida pela letra C, que identifica um código de unidade de medida, ou N, que identifica um nome de unidade de medida.
Ex: MC, MN

O campo de valor é nomeado pela letra V.
Ex: V

Por padrão, são recebidos os códigos e os nomes dos descritores. Para receber somente os códigos ou os nomes, utilize o parâmetro /f/c ou /f/n, como descritos anteriormente.
Se desejar os códigos e os nomes das unidades territoriais e os nomes dos demais descritores, utilize o parâmetro /f/u.

Veja a seguir exemplos dos dados recebidos sobre a produção de feijão, extraídos da tabela 1612 (os 4 primeiros não solicitam registro de cabeçalho):

a) Código e nome (parâmetros /t/1612/n1/1/v/allxp/p/last/c81/2702/h/n)

D1C D1N D2C D2N D3C D3N D4C D4N MC MN V
1 Brasil 109 Área plantada 2012 2012 2702 Feijão (em grão) 1006 Hectares 3182815
1 Brasil 216 Área colhida 2012 2012 2702 Feijão (em grão) 1006 Hectares 2709485
1 Brasil 214 Quantidade produzida 2012 2012 2702 Feijão (em grão) 1017 Toneladas 2794854
1 Brasil 215 Valor da produção 2012 2012 2702 Feijão (em grão) 40 Mil Reais 6216876

b) Código (parâmetros /t/1612/n1/1/v/allxp/p/last/c81/2702/f/c/h/n)

D1C D2C D3C D4C MC V
1 109 2012 2702 1006 3182815
1 216 2012 2702 1006 2709485
1 214 2012 2702 1017 2794854
1 215 2012 2702 40 6216876

c) Nome (parâmetros /t/1612/n1/1/v/allxp/p/last/c81/2702/f/n/h/n)

D1N D2N D3N D4N MN V
Brasil Área plantada 2012 Feijão (em grão) Hectares 3182815
Brasil Área colhida 2012 Feijão (em grão) Hectares 2709485
Brasil Quantidade produzida 2012 Feijão (em grão) Toneladas 2794854
Brasil Valor da produção 2012 Feijão (em grão) Mil Reais 6216876

Observe nos exemplos que a ordem das dimensões recebidas respeita a ordem da especificação dos parâmetros, onde primeiro foi solicitada a unidade territorial (/n1/1), em seguida as variáveis (/v/all), a seguir o período (/p/last) e, por fim, a categoria 'feijão'  da lavoura temporária (/c81/2702).

d) No exemplo a seguir, são solicitados os mesmos dados mas em ordem diferente (/t/1612/n1/1/c81/2702/p/last/v/allxp/f/n/h/n).

D1N D2N D3N D4N MN V
Brasil Feijão (em grão) 2012 Área plantada Hectares 3182815
Brasil Feijão (em grão) 2012 Área colhida Hectares 2709485
Brasil Feijão (em grão) 2012 Quantidade produzida Toneladas 2794854
Brasil Feijão (em grão) 2012 Valor da produção Mil Reais 6216876

A ordem da solicitação é importante pois está associada aos nomes dos campos (D1C, D1N etc) das dimensões, que serão utilizados programaticamente, via linguagem de programação, quando da visualização do resultado.

e) No exemplo a seguir, são solicitados dados para mais de um nível territorial (Brasil e Grandes Regiões).
Observe o nome do nível territorial precedendo os dados (/t/1612/n1/1/n2/all/c81/2702/p/last/v/214/f/n).

NN D1N D2N D3N D4N MN V
Nível Territorial Brasil e Grande Região Lavoura temporária Ano Variável Unidade de Medida Valor
Brasil Brasil Feijão (em grão) 2012 Quantidade produzida Toneladas 2794854
Grande Região Norte Feijão (em grão) 2012 Quantidade produzida Toneladas 120679
Grande Região Nordeste Feijão (em grão) 2012 Quantidade produzida Toneladas 253362
Grande Região Sudeste Feijão (em grão) 2012 Quantidade produzida Toneladas 858398
Grande Região Sul Feijão (em grão) 2012 Quantidade produzida Toneladas 901663
Grande Região Centro-Oeste Feijão (em grão) 2012 Quantidade produzida Toneladas 660752


f) O exemplo a seguir solicita os mesmos dados do exemplo anterior, mas formata o resultado com os códigos ao invés dos nomes (/t/1612/n1/1/n2/all/c81/2702/p/last/v/214/f/c).

NC D1C D2C D3C D4C MC V
Nível Territorial (Código) Brasil e Grande Região (Código) Lavoura temporária (Código) Ano (Código) Variável (Código) Unidade de Medida (Código) Valor
1 1 2702 2012 214 1017 2794854
2 1 2702 2012 214 1017 120679
2 2 2702 2012 214 1017 253362
2 3 2702 2012 214 1017 858398
2 4 2702 2012 214 1017 901663
2 5 2702 2012 214 1017 660752

g) O exemplo a seguir solicita os mesmos dados do exemplo e) acima, mas formata o resultado com os códigos e nomes das unidades territoriais e com os nomes dos demais descritores (/t/1612/n1/1/n2/all/c81/2702/p/last/v/214/f/u).

NN D1C D1N D2N D3N D4N MN V
Nível Territorial Brasil e Grande Região (Código) Brasil e Grande Região Lavoura temporária Ano Variável Unidade de Medida Valor
Brasil 1 Brasil Feijão (em grão) 2012 Quantidade produzida Toneladas 2794854
Grande Região 1 Norte Feijão (em grão) 2012 Quantidade produzida Toneladas 120679
Grande Região 2 Nordeste Feijão (em grão) 2012 Quantidade produzida Toneladas 253362
Grande Região 3 Sudeste Feijão (em grão) 2012 Quantidade produzida Toneladas 858398
Grande Região 4 Sul Feijão (em grão) 2012 Quantidade produzida Toneladas 901663
Grande Região 5 Centro-Oeste Feijão (em grão) 2012 Quantidade produzida Toneladas 660752

 

Limite de consulta aos dados

A consulta aos dados está limitada a 10.000 valores. Para saber quantos valores a sua consulta irá gerar, multiplique a quantidade de seleções feitas em cada uma das dimensões.


Caracteres especiais

Existem símbolos que representam valores especiais, como listados abaixo:

SímboloSignificado
- Zero absoluto, não resultante de um cálculo ou arredondamento.
Ex: Em determinado município não existem pessoas de 14 anos de idade sem instrução.
0 Zero resultante de um cálculo ou arredondamento.
Ex: A inflação do feijão em determinada Região Metropolitana foi 0.
Determinado município produziu 400 kg de sementes de girassol e os dados da tabela são expressos em toneladas.
X Valor inibido para não identificar o informante.
Ex: Determinado município só possui uma empresa produtora de cimento, logo o valor de sua produção deve ser inibido.
.. Valor não se aplica.
Ex: Não se pode obter o total da produção agrícola em determinado município quando os produtos agrícolas são contabilizados com unidades de medida distintas.
... Valor não disponível.
Ex: A produção de feijão em determinado município não foi pesquisada ou determinado município não existia no ano da pesquisa.
Letra A a Z (exceto X) Significa uma faixa de valores. Varia em função da tabela (se for o caso).
Ex: O nível de precisão da produção estimada de combustíveis está na faixa A (até 5%).


Exemplo de dados recebidos no formato JSON

Uma solicitação de dados como no exemplo d) acima (/t/1612/n1/1/c81/2702/p/last/v/allxp/f/n/h/n) resulta em dados recebidos no formato JSON, como abaixo:

[
  {
    "D1N": "Brasil",
    "D2N": "Feijão (em grão)",
    "D3N": "2012",
    "D4N": "Área plantada",
    "MN": "Hectares",
    "V": "3182815"
  },
  {
    "D1N": "Brasil",
    "D2N": "Feijão (em grão)",
    "D3N": "2012",
    "D4N": "Área colhida",
    "MN": "Hectares",
    "V": "2709485"
  },
  {
    "D1N": "Brasil",
    "D2N": "Feijão (em grão)",
    "D3N": "2012",
    "D4N": "Quantidade produzida",
    "MN": "Toneladas",
    "V": "2794854"
  },
  {
    "D1N": "Brasil",
    "D2N": "Feijão (em grão)",
    "D3N": "2012",
    "D4N": "Valor da produção",
    "MN": "Mil Reais",
    "V": "6216876"
  }
]