# Tipologia

> API que retorna a **tipologia de um endereço brasileiro** — finalidade, espécie cadastral, tipo de moradia e indicador de multiplicidade — usando como fonte primária o CNEFE do Censo IBGE 2022.

**Base**: `https://api.prismadata.io/v1`

**Autenticação**: header `X-Apikey` (ou query `api_key`). Detalhes em [Autenticação](autenticacao.md).

**Formato de resposta**: JSON plano com campos `prismadata__<serviço>__<campo>`; em lote, dicionário indexado pelas chaves enviadas. Detalhes em [Formato de Resposta](guias/formato-de-resposta.md).

## Endpoints

### `GET /location/tipologia`

Retorna a tipologia CNEFE (finalidade, espécie, indicador de estabelecimento, tipo de moradia) do endereço mais próximo da coordenada solicitada. Sempre responde 200 OK. Verifique o campo `cobertura` no payload: quando `false`, `motivo_sem_cobertura` indica a razão (FORA_DE_AREA_BRASIL, CNEFE_NAO_CADASTRADO, DISTANCIA_EXCESSIVA). `distancia_match_metros` é a distância geodésica até o endereço CNEFE mais próximo — use para julgar a confiabilidade do match.

**Exemplo curl**:

```bash
curl -X GET "https://api.prismadata.io/v1/location/tipologia?lat=-19.9323&lng=-43.9351" \
  -H "X-Apikey: SEU_TOKEN"
```

**Parâmetros**:

| Nome | Local | Tipo | Obrigatório | Descrição |
|------|-------|------|-------------|-----------|
| `lat` | query | number | sim | Latitude WGS84 do ponto a consultar. |
| `lng` | query | number | sim | Longitude WGS84 do ponto a consultar. |

**Response 200** (`application/json`):

> Sucesso. Verifique `cobertura` e `motivo_sem_cobertura` no payload.

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `prismadata__tipologia__latitude` | number | sim | Latitude solicitada. |
| `prismadata__tipologia__longitude` | number | sim | Longitude solicitada. |
| `prismadata__tipologia__finalidade` | string \| null | não | Finalidade do endereco. Valores possiveis: `RESIDENCIAL`, `NAO_RESIDENCIAL`, `MISTO`, `INDETERMINADO`. `null` quando o endereco nao tem cobertura CNEFE ou a finalidade nao pode ser determinada com seguranca (consulte `finalidade_origem`). |
| `prismadata__tipologia__finalidade_origem` | string \| null | não | Origem do valor de `finalidade`. `CNEFE` — declarada explicitamente pelo IBGE. `DERIVADO` — inferida a partir da especie cadastral ou tipo de moradia. `AUSENTE` — a especie eh ambigua e nao permite inferencia. `null` quando o endereco nao tem cobertura CNEFE. |
| `prismadata__tipologia__especie` | string \| null | não | Especie cadastral do endereco conforme CNEFE-IBGE 2022. Valores possiveis: `DOMICILIO_PARTICULAR`, `DOMICILIO_COLETIVO`, `ESTABELECIMENTO_AGROPECUARIO`, `ESTABELECIMENTO_DE_ENSINO`, `ESTABELECIMENTO_DE_SAUDE`, `ESTABELECIMENTO_DE_OUTRAS_FINALIDADES`, `EDIFICACAO_EM_CONSTRUCAO_OU_REFORMA`, `ESTABELECIMENTO_RELIGIOSO`. `null` quando o endereco nao tem cobertura CNEFE. |
| `prismadata__tipologia__indicador_estabelecimento` | string \| null | não | Multiplicidade do estabelecimento no endereco. Valores possiveis: `UNICO`, `MULTIPLO_ATE_10`, `MULTIPLO_MAIS_DE_10`, `MULTIPLO_DESCONHECIDO`. Quando o valor eh `MULTIPLO_*`, o endereco tem multiplas unidades cadastradas (tipico de shopping centers, predios comerciais, condominios) e a tipologia retornada eh uma amostra entre elas. `null` em enderecos residenciais ou sem cobertura. |
| `prismadata__tipologia__tipo_moradia` | string \| null | não | Classificacao do tipo de moradia quando o endereco eh residencial. Valores possiveis: `CASA`, `CASA_DE_VILA_OU_CONDOMINIO`, `APARTAMENTO`, `OUTROS`. `null` em enderecos nao-residenciais ou sem cobertura. |
| `prismadata__tipologia__cobertura` | boolean | sim | Indica se foi possivel encontrar tipologia para a coordenada solicitada. Quando `false`, consulte `motivo_sem_cobertura`. |
| `prismadata__tipologia__confianca` | string \| null | não | Classificacao qualitativa da confiabilidade do resultado. `ALTA`: match preciso em endereco cadastrado com unidade unica. `MEDIA`: match parcialmente impreciso (proximidade geografica ou endereco multi-unidade — a tipologia retornada eh uma amostra). `BAIXA`: resultado pouco confiavel; use com cautela. `null` quando sem cobertura. |
| `prismadata__tipologia__distancia_match_metros` | number \| null | não | Distancia geodesica em metros entre a coordenada solicitada e o endereco CNEFE retornado. `0.0` quando o endereco foi encontrado exatamente. `null` quando sem cobertura. |
| `prismadata__tipologia__motivo_sem_cobertura` | string \| null | não | Quando `cobertura=false`, indica a razao. `FORA_DE_AREA_BRASIL` — coordenada fora do territorio brasileiro. `CNEFE_NAO_CADASTRADO` — regiao sem cobertura na base CNEFE. `DISTANCIA_EXCESSIVA` — endereco CNEFE mais proximo esta acima do limite aceito. |

**Outros códigos**: 401, 403, 422, 429

---

### `GET /location/tipologia/endereco`

Retorna a tipologia (finalidade, espécie cadastral, tipo de moradia) do endereço CNEFE-IBGE 2022 correspondente ao endereço informado. O endereço pode ser passado de duas formas: - Como string única via `endereco_completo`. - Como campos individuais (`cep`, `numero`, `logradouro`, etc). Quando os campos individuais são fornecidos, eles têm prioridade sobre o que for extraído de `endereco_completo`. O campo `match_method` no payload indica o tipo de match obtido (consulte a descrição do campo). Sempre responde 200 OK. Verifique `cobertura` e `motivo_sem_cobertura` para distinguir os casos sem resultado.

**Exemplo curl**:

```bash
curl -X GET "https://api.prismadata.io/v1/location/tipologia/endereco" \
  -H "X-Apikey: SEU_TOKEN"
# Params opcionais: endereco_completo=string, cep=01310-100, numero=string, tipo_logradouro=string, titulo_logradouro=string, logradouro=string, localidade=string, municipio=string, estado=string
```

**Parâmetros**:

| Nome | Local | Tipo | Obrigatório | Descrição |
|------|-------|------|-------------|-----------|
| `endereco_completo` | query | string \| null | não | Endereço completo em uma string. Quando passado, libpostal extrai os campos. |
| `cep` | query | string \| integer \| null | não | CEP do endereço. |
| `numero` | query | string \| integer \| null | não | Número do endereço. |
| `tipo_logradouro` | query | string \| null | não | Tipo do logradouro (ex: Rua, Avenida). |
| `titulo_logradouro` | query | string \| null | não | Título do logradouro (ex: Doutor, São). |
| `logradouro` | query | string \| null | não | Nome do logradouro. |
| `localidade` | query | string \| null | não | Localidade (frequentemente bairro). |
| `municipio` | query | string \| null | não | Município. |
| `estado` | query | string \| null | não | UF (sigla ou nome). |

**Response 200** (`application/json`):

> Sucesso. Verifique `cobertura` e `match_method` no payload.

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `prismadata__tipologia__latitude` | number \| null | não | Latitude do endereco CNEFE associado ao input. `null` quando o endereco nao pode ser resolvido. |
| `prismadata__tipologia__longitude` | number \| null | não | Longitude do endereco CNEFE associado ao input. `null` quando o endereco nao pode ser resolvido. |
| `prismadata__tipologia__finalidade` | string \| null | não |  |
| `prismadata__tipologia__finalidade_origem` | string \| null | não |  |
| `prismadata__tipologia__especie` | string \| null | não |  |
| `prismadata__tipologia__indicador_estabelecimento` | string \| null | não |  |
| `prismadata__tipologia__tipo_moradia` | string \| null | não |  |
| `prismadata__tipologia__cobertura` | boolean | sim |  |
| `prismadata__tipologia__confianca` | string \| null | não |  |
| `prismadata__tipologia__distancia_match_metros` | number \| null | não | Distancia geodesica em metros entre o endereco cadastrado retornado e o endereco resolvido a partir do input. `0.0` quando o endereco do input foi encontrado exatamente. `null` quando o endereco nao foi resolvido. |
| `prismadata__tipologia__motivo_sem_cobertura` | string \| null | não | Quando `cobertura=false`, indica a razao. `FORA_DE_AREA_BRASIL`, `CNEFE_NAO_CADASTRADO`, `DISTANCIA_EXCESSIVA` (mesmas semanticas do /tipologia), ou `ENDERECO_NAO_RESOLVIDO` quando o endereco informado nao pode ser interpretado. |
| `prismadata__tipologia__match_method` | string | sim | Tipo de match entre o input e o resultado. `EXATO_ESTRUTURADO` — input com campos estruturados casou exatamente com um endereco cadastrado. `EXATO_TEXTO` — input como string casou exatamente apos parsing. `APROXIMADO` — resultado obtido por proximidade geografica do endereco solicitado (consulte `distancia_match_metros` e `confianca`). |
| `prismadata__tipologia__cep` | string \| null | não | CEP do endereco geocodificado. |
| `prismadata__tipologia__logradouro` | string \| null | não | Logradouro do endereco geocodificado. |
| `prismadata__tipologia__numero` | integer \| null | não | Numero do endereco geocodificado. |
| `prismadata__tipologia__localidade` | string \| null | não | Localidade (frequentemente bairro) do endereco geocodificado. |
| `prismadata__tipologia__municipio` | string \| null | não | Municipio do endereco geocodificado. |
| `prismadata__tipologia__uf` | string \| null | não | UF (sigla) do endereco geocodificado. |
| `prismadata__tipologia__endereco_completo` | string \| null | não | Endereco completo formatado do resultado. |
| `prismadata__tipologia__score_qualidade_geocodificacao` | number \| null | não | Score de qualidade da geocodificacao (0-100). Mesma escala do /geocoder — 100 = maxima confianca. |
| `prismadata__tipologia__classificacao_qualidade_geocodificacao` | string \| null | não | Classe de qualidade da geocodificação, derivada do score (0-100): - `MUITO_ALTA` (score 100): endereço localizado com a maior confiança. - `ALTA` (score de 90 a menos de 100): endereço localizado com alta confiança. - `MEDIA` (score de 50 a menos de 90): localização plausível; vale conferir em usos sensíveis. - `BAIXA` (score de 30 a menos de 50): localização incerta; valide antes de usar. - `MUITO_BAIXA` (score acima de 0 e abaixo de 30): localização pouco confiável; não use sem validação. - `CENTROIDE_MUNICIPIO` (score 5): o endereço não foi localizado, mas o município foi; a coordenada é o centro do município, sem precisão de endereço. - `NAO_GEOCODIFICADO` (score 0): não foi possível localizar o endereço (ex.: texto ininteligível); a coordenada não deve ser usada. |

**Outros códigos**: 401, 403, 422, 429

---

### `POST /location/tipologia/batch`

Lookup de tipologia em batch por lat/lng. Recebe um dict de até 1024 coordenadas indexadas por chaves definidas pelo cliente e retorna a tipologia de cada uma, preservando as mesmas chaves na resposta.

**Exemplo curl**:

```bash
curl -X POST "https://api.prismadata.io/v1/location/tipologia/batch" \
  -H "X-Apikey: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "p1": {
           "lat": -19.9323,
           "lng": -43.9351
         }
       }'
```

**Request body** (`application/json`):

Dicionário `{string: object}`.
Dict indexado por chaves do cliente. Cada valor contém `lat` e `lng`. Até 1024 itens por chamada.

**Response 200** (`application/json`):

> Sucesso. Dict com mesmas chaves do request, cada valor com payload do /tipologia ou `null` se aquele item falhou.

Dicionário `{string: object}`.
Dict indexado pelas chaves enviadas pelo cliente. Cada valor contem os campos do response do /tipologia.

**Outros códigos**: 401, 403, 422, 429

---

### `POST /location/tipologia/endereco/batch`

Lookup de tipologia em batch por endereço. Recebe um dict de até 512 endereços indexados por chaves do cliente. Cada valor pode conter `endereco_completo` (string) ou campos estruturados (`cep`, `numero`, `logradouro`, etc). Retorna a tipologia de cada um, preservando as chaves.

**Exemplo curl**:

```bash
curl -X POST "https://api.prismadata.io/v1/location/tipologia/endereco/batch" \
  -H "X-Apikey: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "p1": {
           "endereco_completo": "string",
           "cep": "01310-100",
           "numero": "string",
           "tipo_logradouro": "string",
           "titulo_logradouro": "string",
           "logradouro": "string",
           "localidade": "string",
           "municipio": "string",
           "estado": "string"
         }
       }'
```

**Request body** (`application/json`):

Dicionário `{string: object}`.
Dict indexado por chaves do cliente. Cada valor contém `endereco_completo` ou campos estruturados (`cep`, `numero`, `logradouro`, etc). Até 512 itens por chamada.

**Response 200** (`application/json`):

> Sucesso. Dict com mesmas chaves do request, cada valor com payload do /tipologia/endereco ou `null` se aquele item falhou.

Dicionário `{string: object}`.
Dict indexado pelas chaves enviadas pelo cliente. Cada valor contem os campos do response do /tipologia/endereco.

**Outros códigos**: 401, 403, 422, 429

---

### `GET /location/tipologia/metadata`

Retorna metadata da versão de dados CNEFE atualmente carregada (versão, data de referência, total de endereços, raio máximo).

**Exemplo curl**:

```bash
curl -X GET "https://api.prismadata.io/v1/location/tipologia/metadata" \
  -H "X-Apikey: SEU_TOKEN"
```

**Response 200** (`application/json`):

> Metadata da versao de dados atualmente carregada.

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `prismadata__tipologia__versao_dados` | string | sim | Identificador da versao dos dados carregada. Util para reproduzibilidade entre chamadas. |
| `prismadata__tipologia__data_referencia_cnefe` | string | sim | Data de referencia do Censo CNEFE-IBGE usado. |
| `prismadata__tipologia__total_enderecos_carregados` | integer | sim | Quantidade de enderecos com tipologia disponivel. |
| `prismadata__tipologia__raio_max_metros` | number | sim | Distancia maxima (em metros) em que um endereco CNEFE eh considerado match valido para uma coordenada solicitada. |
| `prismadata__tipologia__denorm_aplicada` | boolean | sim | True quando a materializada `cnefe_tipologia_geom` ja tem denormalizacao de `size` e `cod_setor_cnefe` aplicada (viabiliza queries agregadas sem join). |
| `prismadata__tipologia__enderecos_sem_setor_censitario` | integer | sim | Contagem estimada de enderecos em `cnefe_tipologia_geom` com `cod_setor_cnefe` `null` (~2% do total; enderecos sem correcao CNEFE-Faces). |
| `prismadata__tipologia__dompp_municipio_disponivel` | boolean | sim | True quando a materializada `dompp_municipio` existe e esta populada (denominador de domicilios particulares por municipio IBGE, consumido por produtos internos). |
| `prismadata__tipologia__pontos_disponivel` | boolean | sim | True quando o servico consegue devolver pontos individuais dentro de um poligono (depende da denormalizacao aplicada). |
| `prismadata__tipologia__shape_pontos_max` | integer | sim | Numero maximo de pontos que uma consulta interna de pontos residenciais retorna por request. Consumidor interno degrada para agregado quando excede o limite. |

**Outros códigos**: 401, 403, 429

---

## Recursos relacionados

- Documentação Redoc interativa: https://prismadata.io/redoc.html#tag/Tipologia
- OpenAPI só deste produto (JSON): https://prismadata.io/llm/openapi/tipologia.json
- OpenAPI completo: https://prismadata.io/openapi.yaml
- Índice geral: https://prismadata.io/llms.txt