O diagnóstico por setor

O diagnóstico por setor mostra uma cidade em pedaços de uns 450 moradores, os setores censitários do IBGE. Para cada setor, ele traz duas coisas lado a lado:

• O que o IBGE contou no Censo 2022: é dado observado.
• O que só a população sintética sabe: é modelado e vem acompanhado do erro dela naquele setor.

É o mesmo para todo cliente. Ele é calculado uma vez por release e não usa os dados do seu projeto. O chat pode cruzá-lo com o contexto e os documentos do projeto.

O que é observado

Vem dos agregados por setor do Censo 2022, como o IBGE publicou:

Variável	Categorias
idade_sexo	homens e mulheres em 11 faixas de idade, de 0–4 a 70 ou mais
cor_ou_raca	branca, preta, amarela, parda, indígena
alfabetizacao_15_mais	sabe ou não sabe ler e escrever (15 anos ou mais)
domicilios	domicílios particulares ocupados e moradores por domicílio
renda_responsavel	responsáveis, renda média e mediana dos responsáveis com renda

Onde o IBGE não publicou um número, por sigilo estatístico ou porque não se aplica, ele vem nulo com o motivo: sigilo_ibge ou nao_se_aplica.

Sobre a renda do responsável: o IBGE mede só a renda de quem responde pelo domicílio. Ela não é a renda do domicílio e não serve para ordenar territórios por pobreza.

O que é modelado

Vem da população sintética da release, uma pessoa por morador. Cada variável aparece sozinha, sem cruzar com outra:

Variável	Quem entra	Categorias	O erro mostrado é o de
faixa_renda	14 anos ou mais	sem renda, até R$ 706, de 706 a 1.412, de 1.412 a 2.824, de 2.824 a 5.648, acima de 5.648	renda_responsavel
escolaridade	25 anos ou mais	os cinco níveis de instrução do Censo	alfabetizacao_15_mais
trabalho	14 anos ou mais	trabalha no município, fora dele, sem vínculo	idade_sexo
estudantes	quem estuda e tem menos de 18 anos	creche, pré-escola, fundamental (anos iniciais e finais), médio	idade_sexo

O saneamento

Para cada setor, o diagnóstico traz o saneamento dos domicílios particulares permanentes ocupados, como o IBGE publicou nos agregados por setor do Censo 2022 (características dos domicílios). É dado observado, contado pelo IBGE:

Variável	Categorias
abastecimento_agua	rede geral de distribuição; poço profundo ou artesiano; poço raso, freático ou cacimba; fonte, nascente ou mina; carro-pipa; água da chuva armazenada; rios, açudes, córregos, lagos e igarapés; outra forma
esgotamento	rede geral ou pluvial; fossa séptica ligada à rede; fossa séptica não ligada à rede; fossa rudimentar ou buraco; vala; rio, lago, córrego ou mar; outra forma; sem banheiro nem sanitário
destino_lixo	coletado no domicílio; depositado em caçamba; queimado na propriedade; enterrado na propriedade; jogado em terreno baldio, encosta ou área pública; outro destino
banheiro	com banheiro de uso exclusivo; sem banheiro de uso exclusivo

• O que cada número é: quantos domicílios do setor estão em cada categoria.
• O sigilo do IBGE: onde o IBGE não publicou um número para proteger poucos domicílios, ele vem nulo com o motivo sigilo_ibge. Um número em sigilo nunca é zero: o console diz “sigilo do IBGE”, e um setor com número em sigilo fica fora das listas ordenadas que dependem dele.
• No console: o grupo Saneamento: Censo 2022 (IBGE) colore os setores pela parte dos domicílios na categoria escolhida; o inspetor mostra o saneamento do setor; e os achados trazem os dez setores com mais domicílios sem banheiro de uso exclusivo, com esgoto em vala, rio ou mar, e sem coleta de lixo (queimado, enterrado, jogado em terreno baldio ou outro destino), por posição.
• Pela API e pelo MCP: ?variavel=abastecimento_agua, esgotamento, destino_lixo ou banheiro, sob a mesma abertura da cidade, em listas por setor com o valor e o motivo de cada número que falta.

Os nomes dos setores

O console chama cada setor por um nome, seguido dos quatro últimos dígitos do código: “Centro · setor 0004”. O nome é o primeiro destes que existir:

1. o bairro que a prefeitura informou ao IBGE na malha de setores de 2022;
2. o nome que a própria malha do IBGE dá ao setor: o do aglomerado rural (com as aldeias indígenas, as comunidades quilombolas e as agrovilas) ou o do núcleo urbano;
3. o lugar do OpenStreetMap dentro do setor, como um bairro, uma vila ou um povoado;
4. o limite de bairro do OpenStreetMap que cobre o setor;
5. “perto de” o lugar do OpenStreetMap mais próximo, a até 1 km do centro do setor: “perto de Centro · setor 0001”;
6. o distrito do IBGE.

Como cada nome é escolhido, e por que 1 km, está em Fontes.

• No console: o código inteiro aparece em letra pequena no inspetor, com o distrito e o subdistrito. Um nome que vem do OpenStreetMap leva o crédito “© colaboradores do OpenStreetMap” ao lado dele, no inspetor, e na linha de fontes. A busca aceita o código, o final dele ou o nome do lugar, do bairro ou do distrito, sem acento e sem diferença entre maiúsculas e minúsculas; Enter de novo vai para o próximo setor com o mesmo nome.

• Pela API: GET /v1/municipios/{codigo}/setores/nomes traz, para cada setor:

  • nome, o nome que o console mostra, um por setor da cidade;
  • lugar, o nome do lugar sozinho, sem o “perto de” e sem os dígitos;
  • origem: ibge_bairro, ibge_aglomerado, ibge_nucleo, osm_dentro, osm_limite, osm_perto ou ibge_distrito;
  • credito, o crédito da fonte do nome;
  • distancia_m, no “perto de”, a distância do centro do setor ao lugar, em metros;
  • o bairro, o distrito e o subdistrito do IBGE.

  fontes traz o crédito de cada fonte que os nomes da cidade usam. É dado público, como os contornos, e não pede a abertura da cidade.

• Pelo MCP e no chat: get_city_diagnosis, com uma variavel, get_city_tracts, estimate_growth e get_answers trazem o nome de cada setor que listam (nomes). O crédito de cada fonte dos nomes, com o do OpenStreetMap quando algum nome vem dele, vai em fontes no diagnóstico e em creditos_dos_nomes nas outras três, à parte das fontes dos números delas. O assistente do chat chama um setor só pelo nome que a ferramenta deu, ou pelo código quando não há nome; quando um nome vem do OpenStreetMap, a resposta termina com a nota “Nomes de lugares: © colaboradores do OpenStreetMap”.

A distância às escolas

Para cada setor e cada etapa, o diagnóstico traz a distância em linha reta do centro do setor à escola mais próxima que oferece a etapa. As etapas são creche, pré-escola, fundamental (anos iniciais e finais) e médio, as mesmas dos estudantes. A distância vem arredondada para 10 m, com o código INEP da escola.

• Que escola conta: a que está ativa no Censo Escolar 2024 e tem matrícula na etapa.
• Onde ela fica: na coordenada que a própria escola declara ao Catálogo de Escolas do INEP. A escola sem coordenada fica de fora, e uma declarada a mais de 5 km do município dela também.
• A busca é nacional: a escola mais próxima de um setor perto da divisa pode estar no estado vizinho.
• A cobertura vem junto: para cada etapa, quantas escolas ativas do município oferecem a etapa e quantas têm coordenada. No país, a cobertura vai de 78% (creche) a 89% (médio), mas cai muito em alguns estados (no Acre, menos de 30%). Onde ela é baixa, a escola mais próxima de um setor pode estar entre as que não têm coordenada, e a distância real é menor que a mostrada.
• O que a distância não diz: se a escola tem vaga, qual o turno, se é pública ou privada, e quanto tempo se leva pela rua.

A distância à saúde

Para cada setor e cada grupo de unidade de saúde, o diagnóstico traz a distância em linha reta do centro do setor à unidade mais próxima do grupo, arredondada para 10 m, com o código CNES da unidade. Os grupos são três:

Grupo	O que conta
atencao_basica	posto de saúde, centro de saúde ou unidade básica, unidade de saúde da família
pronto_atendimento	as unidades de urgência isoladas: pronto-socorro e UPA
hospital	hospital geral, hospital especializado, unidade mista

• Que unidade conta: toda unidade ativa do grupo no Cadastro Nacional de Estabelecimentos de Saúde (CNES), pública ou privada. O cadastro não traz uma marca confiável de atendimento pelo SUS (milhares de unidades básicas municipais aparecem como não SUS), então o diagnóstico não separa as duas.
• A urgência dentro de um hospital conta como hospital: em muitas cidades do interior, a porta de urgência mais próxima é o hospital.
• Onde a unidade fica: na coordenada que ela declara ao CNES. Uma unidade cuja coordenada cai a mais de 5 km do município que ela declara fica de fora, e é contada: no país, são cerca de 2% das unidades.
• A cobertura vem junto: para cada grupo, quantas unidades ativas o município tem, quantas têm coordenada e quantas ficaram de fora pela regra dos 5 km.
• A busca é nacional: a unidade mais próxima de um setor perto da divisa pode estar no município ou no estado vizinho.
• O que a distância não diz: se a unidade atende pelo SUS, o horário, a especialidade e quanto tempo se leva pela rua.
• No console: o grupo Saúde: CNES (Ministério da Saúde) colore os setores pela distância; o inspetor mostra a unidade mais próxima de cada grupo; com o relevo ligado, as unidades aparecem como anéis ao lado dos pontos das escolas; os achados trazem os dez setores mais longe de uma unidade de atenção básica e de um hospital; e Nova unidade de saúde recalcula a distância com uma unidade colocada no mapa, como a escola nova, e diz quantos moradores ficam mais perto.
• Pela API e pelo MCP: ?variavel=saude, sob a mesma abertura da cidade, traz a distância por setor e grupo, em metros, com o código CNES e a cobertura; GET /v1/municipios/{codigo}/saude traz as unidades com coordenada, para os marcadores.

O erro de cada setor

O erro diz o quanto a população sintética erra naquele setor, comparada ao que o IBGE contou ali.

• Como é calculado: para idade × sexo, cor ou raça e alfabetização, é o desvio entre as contagens sintéticas e as do Censo, em proporção do tamanho médio das contagens, só nas células que o IBGE publicou. Para a renda do responsável, é a diferença relativa entre a renda média sintética e a do Censo.
• Que erro cada número leva: a renda, a escolaridade e o trabalho não têm contagem do Censo por setor. Por isso cada número modelado vem com o erro da variável observada mais próxima, a da última coluna da tabela acima.
• O corte: um número modelado só aparece se esse erro for no máximo 0,50. Acima disso, o setor mostra “erro alto demais” (erro_acima_do_corte), e a variável inteira daquele setor fica escondida.
• Setor sem medida: quando o setor tem menos de 20 moradores ou menos da metade das células publicadas, o erro não pode ser medido: ele vem nulo, e o número modelado também não aparece (erro_nao_medido).
• No país: na população v2.0.0, o corte deixa o número modelado em 71% dos setores com moradores, onde vivem 84% das pessoas; na v1.2.0, eram 60% e 71%. Nas capitais e nas regiões mais densas, a cobertura é maior.

O que mais pode faltar

• Menos de 5 pessoas: uma contagem modelada de 1 a 4 pessoas não é publicada (menor_que_k). Para que ela não se deduza pela diferença com o total do setor, a menor contagem vizinha também sai (complementar). Um zero é publicado como zero.
• Setores sem população sintética: em alguns municípios, parte dos setores não tem pessoa sintética, e o modelado aparece como sem_populacao_sintetica, sem erro. O observado do IBGE vem inteiro mesmo assim.

Quanto custa

Nada: o diagnóstico é gratuito desde 12 de outubro de 2026. Abrir uma cidade num projeto só registra a abertura, uma vez por cidade, projeto e release (preços).

Como abrir e ler

• No app: em Nova simulação, escolha Planejamento urbano e a cidade. O painel ao lado mostra os setores, e Abrir o diagnóstico leva ao console da cidade, sem custo. As cidades abertas ficam listadas na página do projeto. No console:
  • As camadas, na coluna da esquerda, escolhem o que colore o mapa: o observado do Censo, o modelado da população sintética, a distância à escola mais próxima por etapa, e o território (a declividade e as edificações de cada setor, do perfil da cidade). Os setores ficam coloridos do menor para o maior valor da cidade, e os sem número aparecem em cinza. Ao passar o mouse, aparecem o número, o erro do setor ou o motivo de o número faltar.
  • O inspetor: clique num setor, ou ache um pelo código ou pelo nome, e ele mostra os moradores e os domicílios contados pelo IBGE, a camada escolhida categoria a categoria com a posição do setor na cidade e o erro contra o corte, a escola mais próxima de cada etapa com a distância e o código INEP, e o relevo e as edificações do setor. Onde um número falta, aparece o motivo.
  • Os números da cidade: setores, setores com número modelado, escolas com coordenada por etapa e o setor mais longe de uma creche.
  • A cidade em pontos: ligue Relevo, edificações e água (3D) e o mapa se inclina sobre o relevo da área urbana (Copernicus DEM, reamostrado a uma grade de pontos), com o chão no tom do uso do solo (MapBiomas), as edificações como blocos (um bloco por um número de edificações dito na legenda, com a altura pela densidade, nunca a altura nem o contorno real), as escolas e por onde a chuva escoa, calculado sobre o relevo (não é vazão nem mancha de inundação). A camada escolhida colore os pontos da cidade. Um município que o relevo não cobre continua na planta.
    • O município inteiro: em volta da área urbana, uma grade mais espaçada cobre o resto do município e uma margem dos vizinhos, em pontos menores e mais apagados. Dentro do município, cada ponto leva o uso do solo do seu setor; na margem, a terra dos vizinhos fica num tom neutro. As duas grades vêm do mesmo modelo de relevo e se encontram sem degrau.
    • As ruas sobre o relevo: as ruas e estradas do mapa de fundo (OpenStreetMap) sobem para a altura do terreno, com o mesmo exagero dos pontos, e as linhas planas do mapa somem enquanto o relevo está ligado. As ruas menores aparecem ao chegar mais perto. É só desenho: a geometria é a do OpenStreetMap, sem tráfego nem sentido das vias.
  • Os achados: listas ordenadas sobre os setores da cidade, como os dez mais longe de uma creche, os dez com mais crianças de 0 a 4 anos, os dez de maior declividade média e os dez com mais edificações, e os setores sem número modelado por motivo. Cada item leva ao setor no mapa. São posições, nunca um corte inventado; o único limite citado é o dos 30% de declividade, da Lei 6.766/1979.
  • Simular uma obra → Nova escola: escolha a etapa e clique no mapa onde a escola ficaria. Cada setor passa a ter a menor entre a distância de hoje e a distância em linha reta do centro do setor ao ponto, e o mapa colore o que cada setor ganha; os números mostram quantos setores ficam mais perto e quantos estudantes da etapa, pelo modelado, moram neles. É um exercício no navegador: nada é enviado nem guardado. O centro do setor vem do contorno simplificado do mapa (cerca de 11 m), e não do contorno completo que o diagnóstico usa.
• Mais ferramentas no console:
  • Novo loteamento: marque os cantos do lote no mapa e diga quantos lotes ele tem. O servidor responde o que o lote pede da cidade: moradores, crianças, a escola e a unidade de saúde mais próximas, saneamento e declividade, com a faixa de cada número (O cenário de crescimento). Com o relevo ligado, o console calcula no navegador a declividade dentro do desenho e a parte com 30% ou mais.
  • Política pública, no navegador, sem enviar nada: escolha quem a política atinge (uma faixa de idade e sexo, de renda, de escolaridade, uma situação de trabalho ou uma etapa escolar) e o mapa mostra onde esse público mora, com o total e os dez setores com mais gente dele.
  • Replay: para uma simulação concluída do projeto que publicou os eventos por setor (contrato de resposta), o console anima a cidade semana a semana e mostra as respostas do contrato.
• Pela API, com uma chave do projeto:
  • GET /v1/diagnosticos/{codigo}/cotacao mostra os setores, o preço (zero; uma cidade aberta antes de 12/10/2026 mostra o que pagou) e se o projeto já abriu a cidade na versão mais nova; uma cidade aberta numa versão anterior traz também release_aberta, a versão em que ela continua sendo lida;
  • POST /v1/diagnosticos/{codigo} abre a cidade, sem custo (pede o escopo simulate). Repetir devolve o mesmo recibo;
  • GET /v1/diagnosticos/{codigo} traz o resumo, e ?variavel=trabalho traz uma variável em listas por setor, com o erro e o motivo de cada número escondido. As respostas dizem a versão servida (release) e a mais nova disponível (release_mais_nova): abrir a versão nova é um pedido seu, nunca automático;
  • ?variavel=escolas traz a distância por setor e etapa, em metros, com o código INEP da escola mais próxima e a cobertura do município;
  • GET /v1/municipios/{codigo}/setores/geometria traz os contornos dos setores em GeoJSON compactado;
  • GET /v1/municipios/{codigo}/relevo traz o relevo da área urbana como uma grade de alturas (com o crédito e o aviso do Copernicus no próprio arquivo), e 404 relief_missing para um município que o relevo não cobre; com ?quadro=municipio, a grade mais espaçada do município inteiro, com uma margem dos vizinhos;
  • GET /v1/municipios/{codigo}/escolas traz as escolas ativas com coordenada, com as etapas de cada uma;
  • GET /v1/diagnosticos lista as cidades abertas;
  • POST /v1/diagnosticos/{codigo}/crescimento diz o que um loteamento novo pede da cidade (O cenário de crescimento).
• Pelo MCP: quote_city_diagnosis, open_city_diagnosis, get_city_diagnosis e estimate_growth.

Fontes e créditos

• IBGE, Censo Demográfico 2022: agregados por setor censitário e rendimento do responsável por setor. Dados abertos do Executivo federal, de livre utilização com o crédito da fonte (Decreto 8.777/2016).
• IBGE, Malha de Setores Censitários 2022: os contornos dos setores e os nomes do bairro, do distrito e do subdistrito de cada um.
• IBGE, Censo Demográfico 2022, Agregados por Setores Censitários (características dos domicílios): o saneamento de cada setor.
• Ministério da Saúde, CNES — Cadastro Nacional de Estabelecimentos de Saúde (Portal de Dados Abertos do SUS): a coordenada e o tipo de cada unidade de saúde.
• INEP, Catálogo de Escolas e Censo Escolar 2024: a coordenada declarada de cada escola e as etapas em que ela tem matrícula. Dados abertos do INEP, de livre utilização com o crédito da fonte (Portaria Inep 631/2025).
• OpenStreetMap: o mapa de fundo da cidade e, nos setores sem bairro do IBGE, o nome do lugar (© colaboradores do OpenStreetMap, ODbL). O recorte, a licença e o método que dá nome a cada setor estão em Fontes.