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)
- 1846: Quarterly GDP at current prices (Brazil)
- 5938: Municipal GDP at current prices (annual, down to municipality)
- 6784: Annual GDP and GDP per capita (Brazil)
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"
What each number is: every record carries the SIDRA period column (code and label, e.g. "Mês (Código)" 202403 / "Mês" "março 2024") and the "Variável" label — the only place that says whether a value is a monthly change, a year-to-date or 12-month accumulation, an index number or a level; read it before adding, subtracting or comparing values. A PNAD rolling quarter ("jun-jul-ago 2026") is a three-month window that moves every month, not a calendar quarter. Revisions: values are what SIDRA publishes at the extraction instant (retrieved_at); IBGE revises published figures (quarterly GDP at each release, PNAD reweighting, annual revisions of PIM/PMC/PMS) and the API keeps no earlier version.
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="<column label>" (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. Very large queries are refused by the source (since 2026-09-16 SIDRA tables are read through the Aggregates API, whose ceiling is lower than SIDRA's old 100,000-value cap: all municipalities × 12 yearly periods fails, × 8 works) — narrow periodos (e.g. "last 4") or raise nivel_territorial.
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.
View input schema
{
"type": "object",
"properties": {
"tabela": {
"type": "string",
"description": "Código da tabela SIDRA (ex: 6579 para estimativas de população, 9514 para censo 2022)"
},
"variaveis": {
"default": "allxp",
"description": "IDs das variáveis separados por vírgula, ou 'allxp' para todas",
"type": "string"
},
"nivel_territorial": {
"default": "1",
"description": "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",
"type": "string"
},
"localidades": {
"default": "all",
"description": "Códigos das localidades separados por vírgula, ou 'all' para todas",
"type": "string"
},
"periodos": {
"default": "last",
"description": "Períodos: 'last' para último, 'all' para todos, ou anos específicos (ex: 2020,2021,2022)",
"type": "string"
},
"classificacoes": {
"description": "Classificações no formato 'id[categorias]' (ex: '2[6794]' para sexo masculino)",
"type": "string"
},
"formato": {
"default": "tabela",
"description": "Formato de saída: 'json' para dados brutos ou 'tabela' para formato legível",
"type": "string",
"enum": [
"json",
"tabela"
]
},
"pagina": {
"default": 1,
"description": "Página de resultados (100 registros por página)",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"campos": {
"description": "Selecionar apenas algumas colunas por rótulo, separadas por vírgula (ex: 'Valor,Ano'). Reduz o volume da resposta. Omitir traz todas.",
"type": "string"
},
"estatisticas": {
"default": false,
"description": "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",
"type": "boolean"
},
"agruparPor": {
"description": "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. Nome curto ('UF', 'estado', 'cidade', 'região') e rótulo parcial ('Federação') são resolvidos, e a resposta diz em `aviso` por qual coluna agrupou; rótulo que casa com duas colunas é recusado em vez de escolhido",
"type": "string"
},
"topN": {
"default": 10,
"description": "Tamanho das listas top/bottom quando estatisticas=true sem agruparPor (padrão: 10, máx: 100)",
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"required": [
"tabela"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}