Consulta de tabelas SIDRA
ibge_sidraQuery IBGE SIDRA tables to retrieve Brazilian census, labor, and economic data. Use table codes and territorial levels to get raw data or compute rankings, averages, and distributions.
Instructions
Queries SIDRA tables (IBGE's Automatic Recovery System).
SIDRA contains data from IBGE surveys like Census, PNAD, GDP, etc.
Common tables:
6579: Population estimates (annual)
9514: Census 2022 population
200: Census population (1970-2010)
4714: Population, territorial area and density (Census 2022)
4099: Unemployment rate (PNAD Contínua, quarterly)
5436: Average real income (PNAD Contínua, quarterly)
6706: GDP at current prices
5938: GDP per capita
Territorial levels:
1: Brazil
2: Region (North, Northeast, etc.)
3: State (UF)
6: Municipality
7: Metropolitan Region
Examples:
Brazil population 2023: tabela="6579", periodos="2023"
Population by state: tabela="6579", nivel_territorial="3"
Census 2022 by municipality: tabela="9514", nivel_territorial="6", localidades="3550308"
Statistics mode: for largest/smallest/mean/median/distribution/ranking questions ("which municipality has the largest population?", "median GDP by state") use estatisticas=true — it computes min/max/mean/median/std-dev/labeled percentiles over ALL data rows BEFORE pagination and returns top/bottom rankings (default 10, cap 100 via topN), so one call answers what would otherwise require paging thousands of records. With agruparPor="" (e.g. "Unidade da Federação", "Ano") it ranks groups by descending sum, each with its own mini-distribution. Queries mixing several variables auto-group by "Variável" (units differ). SIDRA absence markers ("-", "..", "...", "X") are excluded from n. In this mode pagina/campos/formato are ignored and registros comes empty. The query itself still respects SIDRA's official cap of 100,000 values.
ibge_sidra is the low-level engine. Prefer a friendlier wrapper when it fits:
Census themes (1970–2022) → ibge_censo
Economic/social time series → ibge_indicadores
Rank/compare 2–10 localities → ibge_comparar
One municipality's panel → ibge_cidades Use ibge_sidra_tabelas and ibge_sidra_metadados to find a table code and its structure before querying.
Behavior: read-only and idempotent — a live GET against the public IBGE SIDRA API. Returns Markdown plus a typed structuredContent payload.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| topN | No | Tamanho das listas top/bottom quando estatisticas=true sem agruparPor (padrão: 10, máx: 100) | |
| campos | No | Selecionar apenas algumas colunas por rótulo, separadas por vírgula (ex: 'Valor,Ano'). Reduz o volume da resposta. Omitir traz todas. | |
| pagina | No | Página de resultados (100 registros por página) | |
| tabela | Yes | Código da tabela SIDRA (ex: 6579 para estimativas de população, 9514 para censo 2022) | |
| formato | No | Formato de saída: 'json' para dados brutos ou 'tabela' para formato legível | tabela |
| periodos | No | Períodos: 'last' para último, 'all' para todos, ou anos específicos (ex: 2020,2021,2022) | last |
| variaveis | No | IDs das variáveis separados por vírgula, ou 'allxp' para todas | allxp |
| agruparPor | No | Com estatisticas=true, agrupa pela coluna informada (rótulo, ex: 'Unidade da Federação', 'Ano') e ranqueia os grupos por soma decrescente (grupos[0] = maior total), cada grupo com sua mini-distribuição | |
| localidades | No | Códigos das localidades separados por vírgula, ou 'all' para todas | all |
| estatisticas | No | Computa estatísticas (mínimo/máximo/média/mediana/desvio-padrão/percentis) sobre TODOS os registros da consulta, antes da paginação, + ranking top/bottom. Use para 'qual o maior/menor', 'média', 'mediana', 'distribuição', 'ranking'. Quando true, ignora pagina, campos e formato | |
| classificacoes | No | Classificações no formato 'id[categorias]' (ex: '2[6794]' para sexo masculino) | |
| nivel_territorial | No | Nível territorial (código N): 1=Brasil, 2=Região, 3=UF, 6=Município, 7=Região Metropolitana, 8=Mesorregião, 9=Microrregião, 10=Distrito, 11=Subdistrito, 13=RM/RIDE, 14=RIDE, 15=Aglomeração Urbana, 17=Região Geográfica Imediata, 18=Região Geográfica Intermediária, 105=Macrorregião de Saúde, 106=Região de Saúde, 114=Aglomerado Subnormal, 127=Amazônia Legal, 128=Semiárido | 1 |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| nome | Yes | Nome da tabela (quando conhecido) | |
| tabela | Yes | Código da tabela SIDRA consultada | |
| colunas | Yes | Rótulos das colunas, na ordem | |
| paginacao | Yes | Metadados de paginação para continuação | |
| registros | Yes | Registros da página atual: cada um mapeia rótulo da coluna -> valor | |
| provenance | Yes | Bloco de proveniência (contrato v1.0): fonte, URL, período, extração e licença | |
| attribution | Yes | URLs canônicas das fontes desta resposta (lista de atribuição) | |
| estatisticas | No | Bloco estatístico presente quando estatisticas=true (registros vem vazio nesse modo) | |
| totalRegistros | Yes | Total de registros de dados disponíveis (todas as páginas) |