Comparar cidades antes de mudar de emprego, alugar uma casa ou abrir um negócio fica bem mais objetivo quando você usa a API do IBGE: em vez de confiar na opinião de conhecidos e na impressão de uma única visita, você consulta números oficiais de população, renda e trabalho direto na fonte, sem custo e sem cadastro. Este guia mostra o que a API entrega, como montar sua primeira consulta em cinco passos, que dado responde a cada pergunta da decisão e quais limites evitar na leitura dos resultados.
O que a API entrega
Na prática, a API de dados agregados alimenta o SIDRA, o sistema oficial do instituto que disponibiliza os dados das pesquisas e censos realizados pelo IBGE. Isso significa que o mesmo número que aparece em relatório oficial ou em notícia de imprensa está disponível para consulta direta, em formato estruturado, sem precisar navegar por páginas de resultados.
A unidade básica da API é o agregado: cada agregado corresponde a uma tabela de uma pesquisa ou censo, e o conjunto completo vem agrupado por pesquisa. A documentação usa tabelas reais para ensinar o caminho: as tabelas do SIDRA 1705 e 1712 servem de exemplo na documentação oficial, e cada tabela corresponde a exatamente um agregado da API. Ou seja, se você já tem o número de uma tabela que viu em uma notícia ou no próprio SIDRA, já tem meio caminho andado para montar a consulta.
Além dos agregados, o portal de serviço de dados do IBGE oferece outros canais úteis para quem está comparando lugares: a API de Localidades, que cobre as divisões administrativas do Brasil (estados, mesorregiões, microrregiões e municípios), e a API da CNAE, a classificação oficial das atividades econômicas, que ajuda a entender a que ramo pertence cada setor citado nos dados.
5 passos para sua consulta
A consulta cabe em um navegador comum, sem instalar nada. O roteiro abaixo parte do zero e termina com o número que interessa na tela.
- Abra a documentação oficial da API de dados agregados e leia a introdução: ela explica o vocabulário de variáveis, classificações e categorias que aparece nas respostas.
- Escolha o agregado com uma chamada simples em
servicodados.ibge.gov.br/api/v3/agregados: a resposta devolve os agregados agrupados pelas respectivas pesquisas, e você localiza a pesquisa de interesse (população, rendimento, trabalho) pelo nome. - Filtre a busca: o endpoint aceita os parâmetros de período, assunto, classificação, periodicidade e nível, o que encurta a lista quando você já sabe, por exemplo, que quer dados por município.
- Liste as localidades do agregado com
/api/v3/agregados/{agregado}/localidades/{nivel}: aqui você confirma quais cidades a tabela cobre e descobre o identificador de cada uma. - Monte a URL final juntando agregado, período, variável e localidades, e abra no navegador: o JSON de resposta traz os resultados por cidade, prontos para copiar em uma planilha e comparar lado a lado.
Para uma decisão pontual, o navegador resolve. Quando a comparação vira rotina — por exemplo, acompanhar indicadores de várias cidades todo mês — dá para automatizar a coleta com um script simples, no mesmo espírito de decidir quando a automação compensa que explicamos no artigo sobre agentes de IA e quando valem a pena.
Comparar cidades: onde olhar
A tabela abaixo liga cada pergunta típica da decisão ao lugar certo da API procurar a resposta.
| Pergunta da decisão | Onde consultar |
|---|---|
| Quantas pessoas vivem na cidade? | Agregados do Censo Demográfico, no nível município |
| Quanto ganham as famílias? | Agregados de rendimento domiciliar das pesquisas do instituto |
| Como está o emprego local? | Agregados das pesquisas de trabalho, filtrados por município |
| Qual o porte de cada região? | API de Localidades, com estados, mesorregiões e municípios |
| A que ramo pertence cada setor citado? | API da CNAE, a classificação nacional de atividades econômicas |
O ponto central é separar as perguntas: tamanho de mercado, poder de compra e oferta de emprego são dimensões diferentes, e cada uma tem seu agregado. Decidir por uma cidade olhando só a população ignora a dimensão que mais pesa em negócio local, que costuma ser a renda das famílias da vizinhança.
Antes de abrir o negócio
Dado oficial não substitui validação, apenas a torna mais barata. Sobre o próximo passo, o Sebrae recomenda analisar o mercado e identificar oportunidades para descobrir se a ideia tem potencial antes de investir, e a orientação combina bem com a API: o dado do instituto responde quanto existe de mercado em cada cidade; a conversa com clientes reais responde se alguém paga pelo que você pretende oferecer.
Uma sequência curta de checagem antes de assinar qualquer contrato:
- Compare três cidades candidatas nos mesmos agregados, no mesmo período, para não misturar bases.
- Anote o número da tabela e a data de referência de cada dado usado na decisão.
- Faça a pergunta de validação com potenciais clientes na cidade escolhida antes do aluguel e do estoque.
- Defina um limite de investimento compatível com o pior cenário que os números mostraram.
Limites e erros comuns
Três armadilhas aparecem com frequência. Primeira: pesquisas diferentes têm períodos de referência diferentes, então população de um ano somada a renda de outro produz comparação torta. Segunda: município e região metropolitana não são a mesma coisa — o mercado real de uma capital costuma incluir cidades vizinhas. Terceira: estimativa de população e dado censitário convivem no sistema, e a leitura correta depende de saber qual dos dois está na tela.
Um quarto erro vem de fora da API: números de cidade que circulam em redes sociais sem fonte. Antes de usar qualquer estatística viral em uma decisão, confira na origem — a mesma disciplina de checagem que vale para vídeos e imagens manipuladas, detalhada no guia deepfake: 7 checagens para não cair em vídeo falso.