Publicado em 31 de agosto de 2026. Todos os números deste texto foram capturados ao vivo nas APIs do IBGE na data da publicação; nenhum é ilustrativo. As URLs de origem estão ao lado de cada um.
O SIDRA é o Banco de Tabelas Estatísticas do IBGE. Praticamente tudo o que o instituto publica passa por lá: Censo, PNAD Contínua, PIB, produção industrial, pesquisas agropecuárias. É a fonte primária brasileira de estatística pública, e é aberta.
O problema não é o acesso. É que a pergunta que uma pessoa faz — "quantos domicílios têm ligação à rede de esgoto?" — não se parece em nada com o que o SIDRA entende, que é um código de tabela, um conjunto de variáveis, uma classificação, um período e um nível territorial. Entre a pergunta e a consulta existe um passo que quase todo tutorial pula: descobrir qual é a tabela — e, mais difícil, ter certeza de que é aquela mesmo.
Este texto é sobre esse passo. Ele vale para quem consulta o SIDRA por qualquer
caminho: pelo site, pela API, pelo sidrapy, ou por um assistente de IA com o
ibge-br-mcp. O erro que ele
descreve não é do software — é da forma de procurar.
Cada pesquisa (Censo Demográfico, PNAD Contínua, IPCA…) tem suas tabelas, que a API chama de agregados. Cada tabela publica um conjunto de variáveis (o que se mede, com sua unidade), zero ou mais classificações (os cortes: sexo, cor ou raça, situação do domicílio…), uma lista de períodos e uma lista de níveis territoriais (Brasil, região, UF, município, e vários outros). Uma consulta é a escolha de um valor em cada um desses eixos.
Duas consequências práticas, e as duas mordem:
- Uma tabela não cobre todos os níveis territoriais. Existe tabela que só publica Brasil. Pedir UF nela devolve erro, não devolve zero.
- O nome da tabela não diz de qual pesquisa ela é. E é daí que vem o erro que este texto quer evitar.
A busca por nome é o ponto de partida óbvio:
GET https://servicodados.ibge.gov.br/api/v3/agregados?...
Procurando por "esgotamento sanitário" no catálogo, em 31/08/2026, voltaram 108 tabelas. As primeiras da lista são estas:
| Código | Nome (abreviado) |
|---|---|
| 2074 | Domicílios… por existência de banheiro ou sanitário e tipo de esgotamento sanitário |
| 10053 | Domicílios… em setores selecionados para a Pesquisa Urbanística do Entorno |
| 10099 | Domicílios… total e com pelo menos um morador quilombola… |
| 10230 | Domicílios… localizados em Unidades de Conservação… |
| 1453 | Domicílios particulares permanentes por tipo de esgotamento sanitário e abastecimento de água |
Nenhuma das quatro primeiras é a tabela geral. São recortes — entorno urbano, quilombolas, unidades de conservação — que contêm o termo procurado porque também classificam por esgotamento sanitário. A lista está correta; a expectativa é que estava errada. Buscar por nome devolve tudo o que menciona o assunto, não o que é sobre o assunto.
O passo que separa um número certo de um número plausível é este:
GET https://servicodados.ibge.gov.br/api/v3/agregados/{tabela}/metadados
A resposta diz quatro coisas que a lista de busca não diz, e as quatro importam:
pesquisa— de qual pesquisa a tabela é. Este é o campo decisivo.periodicidade— o intervalo de períodos que ela realmente cobre.nivelTerritorial— até onde ela desce.variaveis— o que ela mede, com a unidade.
Vale a pena ver o contraste em dois casos reais, os dois consultados em 31/08/2026.
Tabela 6803, a que responde a pergunta original:
pesquisa: Censo Demográfico
periodicidade: 2022–2022
níveis: N1 (Brasil), N2 (região), N3 (UF), N6 (município)
nome: Domicílios particulares permanentes ocupados, por existência de
ligação à rede geral de distribuição de água…
Tabela 9696, cujo nome, num catálogo, passa fácil por "algo de domicílios":
pesquisa: Pesquisa Nacional por Amostra de Domicílios Contínua anual
periodicidade: 2022–2025
níveis: N1 (Brasil), N2 (Grande Região) — e só
nome: Rendimento médio mensal real domiciliar per capita em domicílios
com televisão, por situação do domicílio e acesso a serviço de
televisão por assinatura no domicílio
As duas falam de domicílios. As duas têm dado de 2022. Uma é do Censo; a outra é da PNAD Contínua e mede renda em domicílio com TV por assinatura. Trocar uma pela outra não dá erro nenhum: dá uma tabela de números que parece resposta.
O autor deste texto cometeu exatamente esse erro, e em escala. O
ibge-br-mcptem um atalho, a ferramentaibge_censo, que traduztema+anoem código de tabela para que ninguém precise saber isso tudo. O mapa desse atalho era escrito à mão. Em 31/08/2026 uma varredura contra o catálogo oficial encontrou 15 das 41 tabelas do mapa fora do Censo Demográfico ou fora do assunto do tema:saneamento/2022 apontava justamente para a 9696;fecundidade/2010, para o INPC de 1990;rendimento/2000, para o Censo Agropecuário;quilombolas/2022, para uma tabela de uso de Internet. Cada uma respondia normalmente, com o rótulo escrito à mão no cabeçalho — dado de outra pesquisa sob um nome que mentia. Nada quebrava, e por isso nada aparecia. As tabelas foram corrigidas e o repositório passou a manter um espelho do catálogo do Censo e um teste que confere, uma a uma, se cada código é do Censo e do assunto que promete. A lição não é sobre esse produto: código de tabela escrito à mão ao lado da descrição escrita à mão é uma combinação que apodrece em silêncio. Confira contra a fonte.
Com a tabela confirmada, a consulta é direta:
GET https://apisidra.ibge.gov.br/values/t/6803/n3/all/v/allxp/p/2022
Lendo os pedaços: tabela t/6803, nível territorial n3 (UF) com all as
unidades, variáveis v/allxp (todas, exceto as de percentual), período
p/2022.
Resultado real, capturado em 31/08/2026 — 27 registros, um por UF mais o Distrito Federal:
| Domicílios particulares permanentes ocupados | |
|---|---|
| Total (soma das 27 unidades) | 72.456.368 |
| Maior — São Paulo | 16.224.248 |
| Minas Gerais | 7.533.434 |
| Rio de Janeiro | 6.152.051 |
| Bahia | 5.088.635 |
| Rio Grande do Sul | 4.256.082 |
| … | |
| Rondônia | 555.099 |
| Tocantins | 513.796 |
| Acre | 261.001 |
| Amapá | 201.021 |
| Menor — Roraima | 177.418 |
E a distribuição, que é o que quase sempre interessa mais do que o topo da lista: média 2.683.569, mediana 1.372.108, desvio-padrão 3.236.025. A média é quase o dobro da mediana. Isso não é curiosidade estatística: é o retrato de uma federação em que uma unidade sozinha responde por 22% do total. Um "top 10" esconderia isso; a distribuição inteira, não.
Fonte: IBGE — SIDRA, Tabela 6803, https://apisidra.ibge.gov.br/values/t/6803/n3/all/v/allxp/p/2022, extraído em 31/08/2026.
1. allxp mistura unidades. Pedir todas as variáveis numa tabela que publica
valor absoluto e percentual devolve as duas coisas na mesma coluna V, sem
que nada avise. Somar isso dá um número sem significado. Ou peça a variável
explicitamente, ou separe por Unidade de Medida antes de qualquer conta.
2. Ausência não é zero. O SIDRA marca ausência com -, .., ... e X,
cada um com um sentido diferente (não aplicável, não disponível, dado
suprimido). Um parser distraído converte tudo em 0 e produz uma série que
desce quando o que aconteceu foi a informação faltar.
3. O código do município tem 7 dígitos, e o sétimo é verificador. São Paulo
é 3550308, não 355030. Truncar o dígito verificador é um erro comum quando
se cruza tabela do IBGE com base de outra origem.
4. Confira por dois caminhos. A verificação que vale é a que usa uma tabela diferente: some os municípios e compare com o total da UF; compare o total do Censo com a estimativa do mesmo ano. Se os dois caminhos fecham, o número está de pé. Se não fecham, você achou alguma coisa — e às vezes é a sua consulta.
Perguntar a um modelo "quantos domicílios brasileiros têm ligação à rede de esgoto?" devolve um número plausível, tirado do treino: talvez certo, talvez de outro censo, sem fonte. O ganho de plugar o SIDRA não é conveniência — é que a resposta passa a ter procedência: a tabela, o período, a URL que reproduz a consulta e a data da extração vêm junto com o valor, e qualquer pessoa pode refazer o caminho.
É o que o ibge-br-mcp faz: 21
ferramentas sobre as APIs do IBGE, com um bloco de procedência em toda resposta,
para clientes que falam MCP — Claude, ChatGPT
e afins. Os três passos deste texto viram ibge_sidra_tabelas →
ibge_sidra_metadados → ibge_sidra; e, para os assuntos mais comuns, os
atalhos ibge_censo, ibge_indicadores, ibge_cidades e ibge_comparar.
Mas o passo 2 continua sendo seu, com ou sem ferramenta. Antes de publicar um número, olhe de qual pesquisa a tabela é. Foi a única coisa que faltava para que quinze erros não tivessem existido.
Servidor: ibge-br-mcp ·
endpoint hospedado em https://ibge.sidneybissoli.com/mcp · pacote npm
ibge-br-mcp · licença MIT. Dados
do IBGE sob o regime brasileiro de dados abertos (Lei 12.527/2011 e Decreto
8.777/2016): uso livre, com a obrigação de creditar a fonte.