API › Location › Tipologia # Tipologia de Endereço Classificação da finalidade e espécie de um endereço (residencial, não residencial, misto) a partir do CNEFE-IBGE, para validação cadastral, prevenção a fraude e inteligência territorial. Categoria Location Atualização CNEFE-IBGE (Censo 2022) Fontes IBGE · CNEFE Entrada Coordenada, endereço ou CNPJ Nesta página Aplicações Conceito Convenção de sinais Formas de consulta Exemplos Atributos retornados Detalhes técnicos Limitações 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. Formas de consulta da Tipologia de Endereço Três entradas possíveis. Coordenada entra direto na consulta ao CNEFE. Endereço e CNPJ passam antes por uma etapa de geocodificação que os converte em coordenada. A consulta devolve três blocos: localização, classificação e qualidade & cobertura. O que você tem O que volta Coordenada lat e lng em WGS84 entrada direta Endereço texto livre ou campos passa pela geocodificação CNPJ somente o número passa pela geocodificação entra direto, sem geocodificação Geocodificação o endereço vira uma coordenada qualidade herdada Tipologia CNEFE consulta sobre a coordenada Localização coordenada casada e distância ao match Classificação finalidade, espécie, moradia, multiplicidade Qualidade & cobertura cobertura, confiança e motivo Formas de consulta da Tipologia de Endereço Mesma informação da versão ampla, empilhada: coordenada entra direto na consulta; endereço e CNPJ passam por geocodificação; o resultado é um bloco com três grupos de campos. O que você tem Coordenada lat e lng em WGS84 · entrada direta Endereço texto livre ou campos via geocodificação CNPJ somente o número via geocodificação Geocodificação o endereço vira uma coordenada qualidade herdada pelo cálculo entra direto Tipologia CNEFE consulta sobre a coordenada O que volta Localização coordenada casada e distância ao match Classificação finalidade, espécie, moradia, multiplicidade Qualidade & cobertura cobertura, confiança e motivo 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 ]()