T – para especificar a tabela de onde se deseja extrair os dados

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

Nota

O formato de um código de período é determinado pela periodicidade de liberação da tabela SIDRA consultada.

Para tabelas de divulgação anual, o código possui 4 dígitos no formato AAAA, e indica o ano da ocorrência desejada

Para os demais casos, o código de período possui 6 dígitos no formato AAAASS, onde AAAA indica o ano e SS número de sequência da ocorrência que, conforme a periodicidade, pode representar um mês (01 a 12), um trimestre (01 a 04), um semestre (01 ou 02), entre outros.

V – para especificar as variáveis

Nota

Variáveis com códigos superiores a 1.000.000 identificam variáveis de percentual calculadas automaticamente.

A disponibilidade de uma variável derivada deve ser consultada para cada tabela.

G – para especificar uma visão territorial

Notas

• A disponibilidade de dados para uma determinada visão territorial deve ser consultada para cada tabela.
• Todas as unidades territorais da visão serão apresentadas na tabela de resultado, mesmo quando não houver disponibilidade. Nestes casos, o valor "..." será retornado.
• Quando utilizado o parâmetro G, não será possível utilizar o parâmetro Ni para especificar níveis territoriais avulsos.

Ni – para especificar níveis territoriais e suas unidades

O valor de Ni identifica o nível territorial (por exemplo N1 – Brasil, N2 – Grande Região, N3 – Unidade da Federação, N6 – Município, etc), e é seguido por uma seleção de unidades territoriais a serem consultadas. Este parâmetro pode ser utilizado mais de uma vez para especificar unidades territoriais em níveis distintos.

Notas

• A disponibilidade de dados para um determinado nível territorial deve ser consultada para cada tabela.
• A consulta, por padrão, não retorna unidades territoriais extintas. Caso seja necessário obter valores também para territórios extintos, tanto para consultas do tipo /all quanto por código (por exemplo as UFs Fernando de Noronha - 20 e Guanabara - 34), deve-se acrescentar na lista de parâmetros da consulta /u/y.
• Quando utilizado o parâmetro Ni, não será possível utilizar o parâmetro G para especificar uma visão territorial pré-definida.

Ci – para especificar as classificações da tabela e suas categorias

O valor de Ci identifica uma classificação da tabela (por exemplo C1 – Situação do domicílio, C2 – Sexo, C81 – Produtos da Lavoura Temporária, etc), e é seguido por uma seleção de categorias a serem consultadas.

H – para especificar se o resultado recebido será precedido por um registro de cabeçalho (header)

O registro de cabeçalho, quando presente, será o primeiro registro apresentado, e identificará o código e/ou o nome de cada uma das dimensões da tabela de resultado.

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

F – para especificar o formato dos campos apresentados no resultado

Especifique /f/a para receber os códigos e os nomes dos descritores (valor padrão, caso o parâmetro f não seja especificado).
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 territoriais consultadas, e o nome dos demais descritores.

D – para especificar com quantas casas decimais serão formatados os valores numéricos

Especifique /d/s para formatar os valores com o número de casas decimais padrão para cada variável (valor default, caso o parâmetro d não seja especificado).
Especifique /d/m para formatar os valores com o número 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 número fixo de casas decimais, entre 0 e 9.

Campos dos registros

Os dados serão recebidos no formato especificado, iniciando pelo registro de cabeçalho (quando requisitado) seguido pelos registros de valor.

Cada registro de valor contém, além do próprio valor de resultado, diversos campos para identificação deste registro, conforme a especificado pelo parâmetro F. Podem estar presentes os códigos e/ou os nomes dos descritores do valor em cada dimensão, e o código e/ou o nome da unidade de medida.

Os campos dos registros podem ser resumidos da seguinte forma:

• O campo V indicando o valor do registro. Contém um número ou caractere especial, quando aplicável.
• Os campos referentes à unidade de medida. O campo MC identifica o código da unidade de medida, e MN o seu nome.

• Os campos de dimensão da tabela, que identificam cada registro conforme seu descritor. São códigos de 3 caracteres iniciados pela letra D, seguida por um dígito de sequência entre 1 e 9, e a letra C ou N para identificar um código ou nome (ex. D1C, D1N, D2C, D2N, etc).

• Caso haja seleção de unidades territoriais de diferentes níveis territoriais (como no exemplo 7 da descrição do parâmetro Ni), o registro também incluirá campos de identificação do nível territorial, para que se saiba a que nível cada unidade territorial consultada pertence.

  O campo NC identifica o código do nível territorial, e NN identifica o nome do nível territorial.

Nota

O número de sequência de uma dimensão na resposta corresponde à ordem em que esta dimensão foi especificada na url de consulta.

Na consulta t/1612/c81/2702/p/last/v/allxp/n1/1, por exemplo, a dimensão D1C identificará o código da categoria, D2C o período e D3C a variável.

Caracteres especiais

Os valores consultados através da API Sidra podem eventualmente conter símbolos para representar valores especiais, em razão da natureza dos dados. Estes símbolos se encontram listados abaixo:

Formato de arquivo

O arquivo de resposta pode ser apresentado em formato JSON ou XML. A especificação do formato desejado pode ser feita por query string, ao final da URL, ou pelo campo accept do cabeçalho de requisição HTTP.

Caso o formato não seja especificado, o formato padrão utilizado será JSON. Se ambas as definições estiverem presentes, o formato definido em query string terá prevalência.

Por query string:

• https://apisidra.ibge.gov.br/values/<consulta>?formato=json
• https://apisidra.ibge.gov.br/values/<consulta>?formato=xml

Pelo campo accept do cabeçalho da requisição HTTP:

• Accept: application/json
• Accept: application/xml

[{
    "NN": "Brasil",
    "MN": "Hectares",
    "V": "2765724",
    "D1N": "Brasil",
    "D2N": "Feijão (em grão)",
    "D3N": "2021",
    "D4N": "Área plantada"
},{
    "NN": "Brasil",
    "MN": "Hectares",
    "V": "2613086",
    "D1N": "Brasil",
    "D2N": "Feijão (em grão)",
    "D3N": "2021",
    "D4N": "Área colhida"
},{
    "NN": "Brasil",
    "MN": "Toneladas",
    "V": "2899864",
    "D1N": "Brasil",
    "D2N": "Feijão (em grão)",
    "D3N": "2021",
    "D4N": "Quantidade produzida"
},{
    "NN": "Brasil",
    "MN": "Quilogramas por Hectare",
    "V": "1110",
    "D1N": "Brasil",
    "D2N": "Feijão (em grão)",
    "D3N": "2021",
    "D4N": "Rendimento médio da produção"
},{
    "NN": "Brasil",
    "MN": "Mil Reais",
    "V": "12049373",
    "D1N": "Brasil",
    "D2N": "Feijão (em grão)",
    "D3N": "2021",
    "D4N": "Valor da produção"
}]

<ArrayOfValorDescritoPorSuasDimensoes>
    <ValorDescritoPorSuasDimensoes>
        <V>2765724</V>
        <MN>Hectares</MN>
        <NN>Brasil</NN>
        <D1N>Brasil</D1N>
        <D2N>Feijão (em grão)</D2N>
        <D3N>2021</D3N>
        <D4N>Área plantada</D4N>
    </ValorDescritoPorSuasDimensoes>
    <ValorDescritoPorSuasDimensoes>
        <V>2613086</V>
        <MN>Hectares</MN>
        <NN>Brasil</NN>
        <D1N>Brasil</D1N>
        <D2N>Feijão (em grão)</D2N>
        <D3N>2021</D3N>
        <D4N>Área colhida</D4N>
    </ValorDescritoPorSuasDimensoes>
    <ValorDescritoPorSuasDimensoes>
        <V>2899864</V>
        <MN>Toneladas</MN>
        <NN>Brasil</NN>
        <D1N>Brasil</D1N>
        <D2N>Feijão (em grão)</D2N>
        <D3N>2021</D3N>
        <D4N>Quantidade produzida</D4N>
    </ValorDescritoPorSuasDimensoes>
    <ValorDescritoPorSuasDimensoes>
        <V>1110</V>
        <MN>Quilogramas por Hectare</MN>
        <NN>Brasil</NN>
        <D1N>Brasil</D1N>
        <D2N>Feijão (em grão)</D2N>
        <D3N>2021</D3N>
        <D4N>Rendimento médio da produção</D4N>
    </ValorDescritoPorSuasDimensoes>
    <ValorDescritoPorSuasDimensoes>
        <V>12049373</V>
        <MN>Mil Reais</MN>
        <NN>Brasil</NN>
        <D1N>Brasil</D1N>
        <D2N>Feijão (em grão)</D2N>
        <D3N>2021</D3N>
        <D4N>Valor da produção</D4N>
    </ValorDescritoPorSuasDimensoes>
</ArrayOfValorDescritoPorSuasDimensoes>

Exemplos de consultas

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/2012/c81/2702/h/n)

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

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

Observe nos exemplos que a ordem das dimensões recebidas respeita a ordem de especificação dos parâmetros, onde primeiro solicitamos a unidade territorial (/n1/1), em seguida as variáveis (/v/all), o período (/p/2012) 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/2012/v/allxp/f/n/h/n).

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/2012/v/214/f/n).

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/2012/v/214/f/c).

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/2012/v/214/f/u).