# Validação de Endereços

> O validador de endereços consiste em validar um ou mais endereços com um ou mais sinais de localização (frequentemente obtidos por GPS). Os endereços são comparados com os sinais indicando a concordância ou não da localização do(s) sinal(is) com o(s) endereço(s).

**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/addr_validation/compare_address`

Realiza a comparação de um endereço com determinada coordenada geográfica para avaliar a concordância (proximidade) entre eles.

**Exemplo curl**:

```bash
curl -X GET "https://api.prismadata.io/v1/location/addr_validation/compare_address?lat=-19.9323&lng=-43.9351" \
  -H "X-Apikey: SEU_TOKEN"
# Params opcionais: endereco_completo=string, cep=30130-165, 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 |
|------|-------|------|-------------|-----------|
| `lat` | query | number | sim | Latitude do ponto que se deseja realizar a geocodificação reversa |
| `lng` | query | number | sim | Longitude do ponto que se deseja realizar a geocodificação reversa |
| `endereco_completo` | query | string \| null | não | Endereço completo a ser geocodificado. Não é necessário informá-lo caso os campos que compõem o endereço sejam fornecidos separadamente |
| `cep` | query | string \| integer \| null | não | CEP do endereço a ser geocodificado. |
| `numero` | query | string \| integer \| null | não | Numero do endereço a ser geocodificado |
| `tipo_logradouro` | query | string \| null | não | Tipo do logradouro a ser geocodificado.Ex: Rua, Avenida, etc. |
| `titulo_logradouro` | query | string \| null | não | Ex: Coronel, Senhor, Senhora, Professor, São, etc |
| `logradouro` | query | string \| null | não | O logradouro a ser geocodificado |
| `localidade` | query | string \| null | não | Localidade do endereço. Frequentemente a localidade é o bairro ou região do endereço. |
| `municipio` | query | string \| null | não | Município do endereço. |
| `estado` | query | string \| null | não | Unidade Federativa ou Estado do endereço. |

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

> Successful Response

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `prismadata__valida_endereco_compare__classificacao_campos_endereco` | string | sim | Classificação de concordância geral dos campos do endereço |
| `prismadata__valida_endereco_compare__classificacao_cep` | string | sim | Classificação de concordância do CEP |
| `prismadata__valida_endereco_compare__classificacao_distancia_geodesica` | string | sim | Classificação de concordância da distância geodésica |
| `prismadata__valida_endereco_compare__classificacao_final` | string | sim | Classificação final de concordância entre endereço e coordenada |
| `prismadata__valida_endereco_compare__classificacao_localidade` | string | sim | Classificação de concordância da localidade |
| `prismadata__valida_endereco_compare__classificacao_logradouro` | string | sim | Classificação de concordância do logradouro |
| `prismadata__valida_endereco_compare__classificacao_municipio` | string | sim | Classificação de concordância do município |
| `prismadata__valida_endereco_compare__classificacao_numero` | string | sim | Classificação de concordância do número |
| `prismadata__valida_endereco_compare__classificacao_uf` | string | sim | Classificação de concordância da unidade federativa |
| `prismadata__valida_endereco_compare__distancia_geodesica_m` | number | sim | Distância geodésica em metros entre o endereço geocodificado e a coordenada informada |
| `prismadata__valida_endereco_compare__score_campos_endereco` | number | sim | Score de concordância geral dos campos do endereço |
| `prismadata__valida_endereco_compare__score_cep` | number | sim | Score de concordância do CEP |
| `prismadata__valida_endereco_compare__score_distancia_geodescia` | number | sim | Score de concordância da distância geodésica |
| `prismadata__valida_endereco_compare__score_final` | number | sim | Score final de concordância entre endereço e coordenada |
| `prismadata__valida_endereco_compare__score_localidade` | number | sim | Score de concordância da localidade |
| `prismadata__valida_endereco_compare__score_logradouro` | number | sim | Score de concordância do logradouro |
| `prismadata__valida_endereco_compare__score_municipio` | number | sim | Score de concordância do município |
| `prismadata__valida_endereco_compare__score_numero` | number | sim | Score de concordância do número |
| `prismadata__valida_endereco_compare__score_uf` | number | sim | Score de concordância da unidade federativa |
| `prismadata__valida_endereco_compare__sucesso_geocodificacao_direta` | string | sim | Indica se a geocodificação direta foi realizada com sucesso |
| `prismadata__valida_endereco_compare__sucesso_geocodificacao_reversa` | string | sim | Indica se a geocodificação reversa foi realizada com sucesso |

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

---

### `POST /location/addr_validation/validate_addr`

Valida uma lista de endereços com base no histórico de localização de um dispositivo. A validação indica se cada endereço da lista possui alguma relação com o dispositivo, como "MORADIA", "TRABALHO", "ATIPICO", etc.

**Exemplo curl**:

```bash
curl -X POST "https://api.prismadata.io/v1/location/addr_validation/validate_addr" \
  -H "X-Apikey: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "locations": [
           []
         ],
         "enderecos": [
           "string"
         ]
       }'
```

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

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `locations` | array[array[?]] | sim | Lista de tuplas contendo sinais de localização. |
| `enderecos` | array[string] | sim | Lista de endereços a serem validados |

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

> Successful Response

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `items` | array[object] | sim | Lista de resultados de validação para cada endereço informado |

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

---

### `POST /location/addr_validation/cluster_location_historic`

Realiza uma clusterização espacial dos pontos para identificar locais em que os sinais de localização são frequentes ou prolongados. Além disso, com as informações de timestamp classifica em diferentes graus, qual a afinidade do cluster com as seguintes classificações para o centróide do cluster: 1. MORADIA 2. TRABALHO 3. VISITA_FREQUENTE 4. VISITA_EVENTUAL

**Exemplo curl**:

```bash
curl -X POST "https://api.prismadata.io/v1/location/addr_validation/cluster_location_historic" \
  -H "X-Apikey: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
         []
       ]'
```

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

Lista de `array[?]`.
Lista de tuplas contendo sinais de localização.

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

> Successful Response

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `items` | array[object] | sim | Lista de clusters identificados a partir do histórico de localização |

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

---

## Recursos relacionados

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