Para que serve

Aplicações

A tipologia de endereço responde a uma pergunta simples com peso enorme em antifraude e inteligência territorial: o que existe naquele endereço? A partir de uma coordenada ou de um endereço textual, a API devolve a classificação CNEFE-IBGE — se é residencial ou não residencial, se é casa ou apartamento, se é uma unidade única ou parte de um prédio multi-unidade.

Validação Cadastral e Antifraude

Confira se a finalidade real do endereço (residencial × não residencial) é coerente com o que o usuário declarou no onboarding.

Enriquecimento de Crédito e Risco

Use finalidade, espécie e tipo de moradia como features de contexto do endereço em modelos de concessão e precificação.

KYB e Onboarding de PJ

Sinalize empresas cadastradas em endereços puramente residenciais ou em endereços multi-unidade sem indicação clara de sala.

Inteligência Territorial e Expansão

Caracterize o mix residencial/comercial de uma área para escolha de PDV, seguros e marketing geográfico.

Entendendo o dado

Conceito

A API recebe uma coordenada (lat/lng) ou um endereço e devolve a tipologia do endereço CNEFE correspondente — finalidade, espécie cadastral, tipo de moradia e um indicador de multiplicidade — conforme o Cadastro Nacional de Endereços para Fins Estatísticos (CNEFE) do IBGE. Sempre responde 200 OK: a ausência de resultado é sinalizada por cobertura = false + motivo_sem_cobertura, não por erro HTTP.

Quando a finalidade não é declarada explicitamente pelo IBGE, ela pode ser derivada da espécie cadastral ou do tipo de moradia — o campo finalidade_origem distingue entre CNEFE, DERIVADO e AUSENTE. A cobertura do CNEFE é parcial e endereços densos multi-unidade (prédios comerciais, shoppings, condomínios) retornam uma amostra entre as unidades cadastradas, com confiança reduzida — indicada por indicador_estabelecimento = MULTIPLO_*.

Interpretação

Convenção de Sinais

Três campos concentram a leitura do resultado. Interprete-os em conjunto antes de acionar decisão automática.

●

cobertura: false Não há tipologia para o ponto. O campo motivo_sem_cobertura explica a razão (FORA_DE_AREA_BRASIL, CNEFE_NAO_CADASTRADO, DISTANCIA_EXCESSIVA, ou ENDERECO_NAO_RESOLVIDO no endpoint por endereço) e os demais campos vêm nulos.

○

confianca: ALTA Match preciso em endereço cadastrado com unidade única. Pode ser usado diretamente em decisão.

●

confianca: MEDIA Match parcialmente impreciso: proximidade geográfica ou endereço multi-unidade (a tipologia é uma amostra). Avalie distancia_match_metros antes de decidir.

●

confianca: BAIXA Resultado pouco confiável; use com cautela ou como sinal secundário em um score.

●

indicador_estabelecimento: MULTIPLO_* O endereço tem múltiplas unidades cadastradas (típico de prédio comercial, shopping, condomínio); a tipologia retornada é uma amostra entre elas. Não use o resultado como certeza sobre a unidade específica.

Request

Parâmetros de Entrada

Duas formas de entrada, cada uma em seu endpoint. Para lotes, use as variantes /location/tipologia/batch e /location/tipologia/endereco/batch (até 1024 itens por chamada). Para descobrir a versão dos dados carregada em produção, consulte /location/tipologia/metadata — retorna versao_dados, data_referencia_cnefe, total_enderecos_carregados e raio_max_metros.

Por coordenada

GET /location/tipologia

lat float · obrigatório

Latitude WGS84 do ponto a consultar (entre -90 e 90, exclusivo).

lng float · obrigatório

Longitude WGS84 do ponto a consultar (entre -180 e 180, exclusivo).

Por endereço

GET /location/tipologia/endereco — informe endereco_completo OU os campos separados. Se ambos vierem, os campos estruturados têm prioridade.

endereco_completo string

Endereço em uma única string. O libpostal extrai os campos.

cep string

CEP do endereço (com ou sem máscara).

numero string

Número do endereço.

tipo_logradouro string

Tipo do logradouro (ex.: Rua, Avenida).

titulo_logradouro string

Título do logradouro (ex.: Doutor, São).

logradouro string

Nome do logradouro.

localidade string

Localidade (frequentemente bairro).

municipio string

Município.

estado string

UF (sigla ou nome).

Na prática

Exemplos

Três cenários que cobrem o repertório típico de respostas: residencial unifamiliar bem casado, endereço multi-unidade com amostragem, e coordenada sem cobertura.

A · Residencial unifamiliar GET /v1/location/tipologia?lat=-22.9068&lng=-43.1729

{
  "prismadata__tipologia__latitude": -22.9068,
  "prismadata__tipologia__longitude": -43.1729,
  "prismadata__tipologia__finalidade": "RESIDENCIAL",
  "prismadata__tipologia__finalidade_origem": "CNEFE",
  "prismadata__tipologia__especie": "DOMICILIO_PARTICULAR",
  "prismadata__tipologia__tipo_moradia": "CASA",
  "prismadata__tipologia__indicador_estabelecimento": "UNICO",
  "prismadata__tipologia__cobertura": true,
  "prismadata__tipologia__confianca": "ALTA",
  "prismadata__tipologia__distancia_match_metros": 0.0,
  "prismadata__tipologia__motivo_sem_cobertura": null
}

Endereço unifamiliar bem casado: match exato (distancia_match_metros: 0.0), indicador_estabelecimento: UNICO, confianca: ALTA e finalidade declarada pelo próprio CNEFE. Sinal limpo para decisão.

B · Endereço multi-unidade (amostra) GET /v1/location/tipologia?lat=-23.5614&lng=-46.6559

{
  "prismadata__tipologia__latitude": -23.5614,
  "prismadata__tipologia__longitude": -46.6559,
  "prismadata__tipologia__finalidade": "NAO_RESIDENCIAL",
  "prismadata__tipologia__finalidade_origem": "DERIVADO",
  "prismadata__tipologia__especie": "ESTABELECIMENTO_DE_OUTRAS_FINALIDADES",
  "prismadata__tipologia__tipo_moradia": null,
  "prismadata__tipologia__indicador_estabelecimento": "MULTIPLO_MAIS_DE_10",
  "prismadata__tipologia__cobertura": true,
  "prismadata__tipologia__confianca": "MEDIA",
  "prismadata__tipologia__distancia_match_metros": 12.47,
  "prismadata__tipologia__motivo_sem_cobertura": null
}

Prédio comercial com mais de 10 unidades cadastradas: indicador_estabelecimento: MULTIPLO_MAIS_DE_10. A tipologia retornada é uma amostra entre as unidades — não use como certeza sobre a sala/unidade específica. confianca: MEDIA reforça essa cautela.

C · Coordenada sem cobertura GET /v1/location/tipologia?lat=-13.5&lng=-56.2

{
  "prismadata__tipologia__latitude": -13.5,
  "prismadata__tipologia__longitude": -56.2,
  "prismadata__tipologia__finalidade": null,
  "prismadata__tipologia__finalidade_origem": null,
  "prismadata__tipologia__especie": null,
  "prismadata__tipologia__tipo_moradia": null,
  "prismadata__tipologia__indicador_estabelecimento": null,
  "prismadata__tipologia__cobertura": false,
  "prismadata__tipologia__confianca": null,
  "prismadata__tipologia__distancia_match_metros": null,
  "prismadata__tipologia__motivo_sem_cobertura": "CNEFE_NAO_CADASTRADO"
}

Região sem cobertura na base CNEFE: cobertura: false, motivo_sem_cobertura: CNEFE_NAO_CADASTRADO, demais campos nulos. Trate como "sem sinal" — não como negativa.

Os JSONs acima são ilustrativos. Consulte a lista completa de atributos na próxima seção.

Response

Atributos Retornados

Nomes sem o prefixo prismadata__tipologia__. Enums vêm sempre em MAIUSCULAS_COM_UNDERSCORE.

Localização

latitude

Latitude do ponto: no endpoint por coordenada, é a latitude solicitada; no endpoint por endereço, é a latitude do endereço CNEFE associado (null se o endereço não pôde ser resolvido).

longitude

Longitude do ponto — mesma semântica de latitude.

distancia_match_metros

Distância geodésica em metros entre o input (coordenada ou endereço resolvido) e o endereço CNEFE retornado. 0.0 quando o endereço foi encontrado exatamente; null quando sem cobertura.

Classificação

finalidade

Finalidade do endereço: RESIDENCIAL, NAO_RESIDENCIAL, MISTO ou INDETERMINADO. null quando sem cobertura ou quando a finalidade não pode ser determinada com segurança (consulte finalidade_origem).

finalidade_origem

Origem do valor de finalidade. CNEFE — declarada explicitamente pelo IBGE. DERIVADO — inferida a partir da espécie ou tipo de moradia. AUSENTE — a espécie é ambígua e não permite inferência.

especie

Espécie cadastral conforme CNEFE-IBGE 2022: DOMICILIO_PARTICULAR, DOMICILIO_COLETIVO, ESTABELECIMENTO_AGROPECUARIO, ESTABELECIMENTO_DE_ENSINO, ESTABELECIMENTO_DE_SAUDE, ESTABELECIMENTO_DE_OUTRAS_FINALIDADES, EDIFICACAO_EM_CONSTRUCAO_OU_REFORMA, ESTABELECIMENTO_RELIGIOSO.

tipo_moradia

Classificação do tipo de moradia quando o endereço é residencial: CASA, CASA_DE_VILA_OU_CONDOMINIO, APARTAMENTO, OUTROS. null em endereços não residenciais ou sem cobertura.

indicador_estabelecimento

Multiplicidade do estabelecimento: UNICO, MULTIPLO_ATE_10, MULTIPLO_MAIS_DE_10, MULTIPLO_DESCONHECIDO. Quando MULTIPLO_*, o endereço tem múltiplas unidades cadastradas (shopping, prédio comercial, condomínio) e a tipologia é uma amostra.

Qualidade & cobertura

cobertura

Booleano que indica se foi possível encontrar tipologia para o input. Quando false, consulte motivo_sem_cobertura.

confianca

Classificação qualitativa da confiabilidade: ALTA (match preciso, unidade única), MEDIA (proximidade geográfica ou endereço multi-unidade — amostra), BAIXA (use com cautela). null quando sem cobertura.

motivo_sem_cobertura

Quando cobertura=false, indica a razão: FORA_DE_AREA_BRASIL (coordenada fora do território), CNEFE_NAO_CADASTRADO (região sem cobertura na base), DISTANCIA_EXCESSIVA (endereço CNEFE mais próximo acima do limite), ou ENDERECO_NAO_RESOLVIDO (no endpoint por endereço, quando o input não pôde ser interpretado).

Somente na entrada por endereço

match_method

Retornado apenas em /location/tipologia/endereco. Indica o tipo de match: EXATO_ESTRUTURADO (input com campos estruturados casou exatamente com um endereço cadastrado), EXATO_TEXTO (input como string casou exatamente após parsing), APROXIMADO (resultado obtido por proximidade geográfica — consulte distancia_match_metros e confianca).

Referência

Detalhes Técnicos

Fontes

Cadastro Nacional de Endereços para Fins Estatísticos (CNEFE)
IBGE — Censo Demográfico 2022

Metodologia

Associação da coordenada ou do endereço ao endereço CNEFE correspondente dentro de um raio máximo. Quando a finalidade não é declarada explicitamente pelo IBGE, é derivada da espécie cadastral ou do tipo de moradia (campo finalidade_origem).

Frequência de Atualização

Acompanha as publicações do CNEFE/IBGE. O campo data_referencia_cnefe (via /tipologia/metadata) identifica a versão do Censo em uso.

Cobertura

Endereços cadastrados no CNEFE. A cobertura é parcial; regiões não cadastradas retornam cobertura = false com motivo_sem_cobertura = CNEFE_NAO_CADASTRADO.

Atenção

Limitações

Considere ao utilizar

A cobertura do CNEFE é parcial; parte do território não retorna tipologia (cobertura = false).
Em endereços multi-unidade (prédios, shoppings, condomínios) a tipologia é uma amostra entre as unidades, com confianca reduzida.
Quando não há endereço exato, o resultado vem por proximidade geográfica (match_method: APROXIMADO); avalie distancia_match_metros e confianca antes de acionar decisão automática.
Os dados refletem o Censo de referência e podem defasar frente a mudanças recentes de uso do imóvel (retrofit comercial, novas construções, conversões).

Pronto para testar?

Solicite acesso à API de Tipologia e integre-a a modelos de antifraude, KYB e inteligência territorial.

Solicitar acesso

Documentação > Tipologia de Endereço

Tipologia de Endereço