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. O caminho natural é consultar pelo CNPJ via CNPJ Enriquecido com tipologia=true, que devolve a tipologia do endereço cadastral junto com os dados da RFB numa só chamada. Insumo direto para a Portaria SPA/MF 2.750/2026, que exige de instituições financeiras verificar se o CNPJ está registrado em endereço residencial como indicador de operação irregular de apostas.

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

Formas de consulta

A tipologia é calculada sobre uma coordenada. Você chega até ela por três caminhos, conforme o que a sua esteira já tem em mãos: coordenada, endereço ou CNPJ. Os caminhos de endereço e de CNPJ passam por uma etapa de geocodificação, e é dela que a coordenada usada na consulta ao CNEFE é derivada.

Três caminhos, todos em produção. Caminhos relativos à base `https://api.prismadata.io/v1`.
O que você tem	Consulta individual	Consulta em lote	Lote máximo
Coordenadalat e lng em WGS84	`GET /location/tipologia`	`POST /location/tipologia/batch`	1.024
Endereçotexto livre ou campos estruturados	`GET /location/tipologia/endereco`	`POST /location/tipologia/endereco/batch`	1.024
CNPJdados cadastrais e tipologia do endereço da empresa	`GET /cnpj/{cnpj}/enriched?tipologia=true`	`POST /cnpj/batch/enriched` · `flags.tipologia=true` no corpo	256

Por endereço e por CNPJ, a coordenada vem de geocodificação O resultado herda a qualidade do geocoder. Um endereço mal cadastrado produz coordenada imprecisa, e a tipologia obtida sobre ela reflete essa imprecisão — muitas vezes com confianca: MEDIA e distancia_match_metros elevada. No caminho de CNPJ, a própria resposta traz com que confiança o endereço foi resolvido, em prismadata__pessoa_juridica__qualidade_geocodificacao_classificacao e no score numérico correspondente, junto de prismadata__pessoa_juridica__endereco_existe e prismadata__pessoa_juridica__divergencia_endereco_rfb_geocoder. A coordenada usada na consulta ao CNEFE também volta, em latitude e longitude, o que torna o resultado auditável.
Por CNPJ sem coordenada geocodificável, o bloco de tipologia não é retornado Quando o endereço cadastral do CNPJ não produz coordenada, a resposta traz os dados cadastrais sem o bloco de tipologia. A ausência do bloco é a sinalização de que não houve coordenada para consultar o CNEFE.

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).

Por CNPJ

GET /cnpj/{cnpj}/enriched?tipologia=true — lote em POST /cnpj/batch/enriched com flags.tipologia=true no corpo (até 256 CNPJs por chamada).

A consulta por CNPJ é feita pelo endpoint do produto CNPJ Enriquecido com o flag tipologia=true. O CNPJ é geocodificado internamente a partir do endereço cadastral da Receita Federal, e o bloco de tipologia (prefixo prismadata__tipologia__) volta na mesma resposta que os campos cadastrais (prefixo prismadata__pessoa_juridica__). É o caminho natural para fluxos de KYB e onboarding de PJ, em que a esteira já parte do CNPJ. Quando o endereço cadastral não produz coordenada geocodificável, o bloco de tipologia não é retornado — a ausência do bloco sinaliza que não houve coordenada para consultar o CNEFE.

cnpj path · string

CNPJ de 14 caracteres, com ou sem máscara. Aceita o formato alfanumérico da Receita Federal.

Na prática

Exemplos

Quatro cenários que cobrem o repertório típico de respostas: residencial unifamiliar bem casado, endereço multi-unidade com amostragem, coordenada sem cobertura, e consulta por CNPJ na esteira de onboarding. Os JSONs abaixo foram lidos direto do endpoint.

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.

D · Via CNPJ, na esteira de onboarding GET /v1/cnpj/{cnpj}/enriched?tipologia=true

{
  "prismadata__pessoa_juridica__cnpj": "XXXXXXXX0001XX",
  "prismadata__pessoa_juridica__razao_social": "RAZAO SOCIAL OMITIDA",
  "prismadata__pessoa_juridica__situacao_cadastral": "ATIVA",
  "prismadata__pessoa_juridica__data_abertura": "2024-11-19",
  "prismadata__pessoa_juridica__natureza_juridica_descricao": "Sociedade Empresária Limitada",
  "prismadata__pessoa_juridica__cnae_principal_codigo": "6311900",
  "prismadata__pessoa_juridica__cnae_principal_descricao": "Tratamento de dados, provedores de serviços de aplicação e serviços de hospedagem na Internet",
  "prismadata__pessoa_juridica__porte": "PEQUENA",
  "prismadata__pessoa_juridica__endereco_normalizado": "RUA ALAGOAS, 601 - SAVASSI, BELO HORIZONTE/MG 301301650",
  "prismadata__pessoa_juridica__municipio_nome": "BELO HORIZONTE",
  "prismadata__pessoa_juridica__uf": "MG",
  "prismadata__pessoa_juridica__latitude": "-19.932592",
  "prismadata__pessoa_juridica__longitude": "-43.935406",
  "prismadata__pessoa_juridica__endereco_existe": true,
  "prismadata__pessoa_juridica__divergencia_endereco_rfb_geocoder": false,
  "prismadata__pessoa_juridica__qualidade_geocodificacao_classificacao": "ALTA",
  "prismadata__pessoa_juridica__qualidade_geocodificacao_score": 70,

  "prismadata__tipologia__latitude": -19.932592,
  "prismadata__tipologia__longitude": -43.935406,
  "prismadata__tipologia__finalidade": "NAO_RESIDENCIAL",
  "prismadata__tipologia__finalidade_origem": "DERIVADO",
  "prismadata__tipologia__especie": "ESTABELECIMENTO_DE_SAUDE",
  "prismadata__tipologia__tipo_moradia": null,
  "prismadata__tipologia__indicador_estabelecimento": "MULTIPLO_ATE_10",
  "prismadata__tipologia__cobertura": true,
  "prismadata__tipologia__confianca": "MEDIA",
  "prismadata__tipologia__distancia_match_metros": 0.05,
  "prismadata__tipologia__motivo_sem_cobertura": null
}

Empresa ATIVA, com endereço cadastral em Belo Horizonte/MG geocodificado com qualidade ALTA e sem divergência entre RFB e geocoder. Na mesma resposta, a tipologia CNEFE do ponto: endereço não residencial em edifício com até dez unidades cadastradas — a espécie ESTABELECIMENTO_DE_SAUDE é uma amostra entre as unidades, o que motiva confianca: MEDIA. Uma chamada resolve o cadastro e o sinal territorial — sem uma segunda integração no fluxo. Razão social e CNPJ foram mascarados; os demais valores são os que a API devolveu.

Os JSONs acima são recortes 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