# Fronteiras

> O dado de fronteiras indica se um ponto está localizado em uma faixa de fronteira e traz algumas informações desta fronteira, como proximidade da fronteira, qual é o país mais próximo e se a mancha urbana do município que o ponto se encontra está próximo da faixa de fronteira.

**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

### `POST /location/batch/border`

Consulta em lote a proximidade às fronteiras terrestres brasileiras, com as mesmas informações da consulta por ponto para até 1024 coordenadas. A cobrança é feita por coordenada do lote.

**Exemplo curl**:

```bash
curl -X POST "https://api.prismadata.io/v1/location/batch/border" \
  -H "X-Apikey: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "point1": [
           -23.5505,
           -46.6333
         ],
         "point2": [
           40.7128,
           -74.006
         ]
       }'
```

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

Dicionário `{string: array[number]}`.
Modelo da entrada em batch

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

> Successful Response

Dicionário `{string: object}`.
Dicionário onde as chaves são identificadores únicos para cada ponto consultado

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

---

### `GET /location/border`

Consulta a proximidade de um ponto às fronteiras terrestres brasileiras. Indica se o ponto está na faixa de fronteira, o município de fronteira, o país estrangeiro mais próximo, a cidade gêmea, a tríplice fronteira mais próxima e o índice de exposição geográfica de fronteira.

**Exemplo curl**:

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

**Parâmetros**:

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

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

> Successful Response

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `prismadata__border__area_municipio_integrada_faixa_de_fronteira_km2` | number \| null | não | tamanho da área em quilômetros quadrados do municipio que coincide com a faixa de fronteira. |
| `prismadata__border__area_total_municipio_km2` | number \| null | não | tamanho total da área do município. |
| `prismadata__border__distancia_geodesica_pais_mais_proximo_pt_km` | number \| null | não | a distância em quilômetros do ponto em análise até o país estrangeiro mais proximo. |
| `prismadata__border__distancia_geodesica_pais_mais_proximo_sede_municipio_km` | number \| null | não | distância em quilômetros do ponto até a sede do município de fronteira. A sede do município é o marco zero do município, o ponto do qual o município iniciou o seu crescimento. Em geral é a prefeitura, praça principal ou igreja matriz do município. |
| `prismadata__border__distancia_geodesica_ponto_borda_faixa_de_fronteira_km` | number \| null | não | distância em quilômetros do ponto até a borda da geometria de fronteira definida pelo IBGE. |
| `prismadata__border__municipio_possui_cidade_gemea` | boolean \| null | não | indica se o município em que o ponto se encontra possui uma cidade gêmea em outro pais. Duas cidades são consideradas gêmeas quando as manchas urbanas delas são muito próximas apesar delas estarem em países distintos |
| `prismadata__border__nome_municipio_de_fronteira` | string \| null | não | nome do município de fronteira em que o ponto se encontra. |
| `prismadata__border__pais_mais_proximo` | string \| null | não | nome do pais mais próximo ao município de fronteira em que o ponto se encontra. |
| `prismadata__border__pais_mais_proximo_pt` | string \| null | não | nome do pais de fronteira mais próximo ao ponto propriamente dito. |
| `prismadata__border__ponto_contido_na_faixa_de_fronteira` | boolean \| null | não | indica se o ponto está contido na faixa de fronteira. |
| `prismadata__border__frac_area_municipio_faixa_de_fronteira` | number \| null | não | fração da área do município em que o ponto se encontra que está dentro da área de fronteira. Valor em [0,1] (ex.: 0.325 = 32,5%). |
| `prismadata__border__sede_municipio_dentro_da_faixa_de_fronteira` | boolean \| null | não | indica se a sede do município, que é o marco zero do município, se encontra dentro da faixa de fronteira. |
| `prismadata__border__nome_cidade_gemea_estrangeira` | string \| null | não | nome da cidade gêmea estrangeira do município em que o ponto se encontra. Nulo quando o município não possui cidade gêmea ou quando o ponto não está em município de fronteira. |
| `prismadata__border__pais_cidade_gemea` | string \| null | não | país da cidade gêmea estrangeira. Segue a mesma nomenclatura de `pais_mais_proximo_pt`. |
| `prismadata__border__segundo_pais_mais_proximo_pt` | string \| null | não | nome do segundo país estrangeiro mais próximo ao ponto. Relevante em tríplices fronteiras, onde dois países estão a distâncias comparáveis. |
| `prismadata__border__distancia_geodesica_segundo_pais_km` | number \| null | não | distância em quilômetros do ponto até o segundo país estrangeiro mais próximo. |
| `prismadata__border__ponto_em_area_triplice_fronteira` | boolean \| null | não | indica se o ponto está a até 50 km de um ponto de tríplice fronteira. Tríplices fronteiras são tratadas pelo GAFI/FATF como áreas de risco elevado para PLD/FT. |
| `prismadata__border__distancia_triplice_fronteira_km` | number \| null | não | distância geodésica em quilômetros até a tríplice fronteira mais próxima. Nulo quando essa distância supera 500 km. |
| `prismadata__border__nome_triplice_fronteira` | string \| null | não | nome da tríplice fronteira mais próxima ao ponto. Nulo quando a distância supera 500 km. |
| `prismadata__border__paises_triplice_fronteira` | string \| null | não | países que formam a tríplice fronteira mais próxima ao ponto, em ordem alfabética e separados por `/` (ex.: `ARGENTINA/BRASIL/PARAGUAI`). Nulo quando a distância supera 500 km. |
| `prismadata__border__arco_fronteira` | string \| null | não | arco da faixa de fronteira, conforme classificação do IBGE por UF: `NORTE`, `CENTRAL` ou `SUL`. Nulo quando o ponto não está em município de fronteira. |
| `prismadata__border__score_exposicao_fronteira` | integer | sim | índice determinístico de exposição geográfica à fronteira, de 0 a 100, derivado dos demais campos desta resposta. Três ressalvas de uso: (1) mede a exposição do território, não a pessoa — não é score de risco de cliente e não expressa julgamento sobre quem está no endereço; (2) é insumo da Abordagem Baseada em Risco da instituição e não substitui a metodologia própria exigida pela Circular BACEN 3.978; (3) não deve ser fundamento único para recusa ou encerramento de relacionamento, tanto pelo risco de discriminação territorial quanto pelo direito à revisão do art. 20 da LGPD. Os parâmetros de cálculo estão em `/border/metadata`. |
| `prismadata__border__classificacao_exposicao_fronteira` | string | sim | banda do índice: `RESIDUAL` (0-19), `BAIXA` (20-44), `MODERADA` (45-69) ou `ELEVADA` (70-100). |
| `prismadata__border__versao_metodologia_score` | string | sim | versão semver da metodologia usada no cálculo. Versões anteriores permanecem disponíveis e documentadas em `/border/metadata`. |
| `prismadata__border__score_componente_proximidade_internacional` | integer \| null | não | componente D1: proximidade à linha internacional, em escala logarítmica ancorada em 100 na linha, 25 na borda da faixa e 0 a partir de 500 km. |
| `prismadata__border__score_componente_triplice_fronteira` | integer \| null | não | componente D2: proximidade a ponto de tríplice fronteira. Vale 100 no Iguaçu, única citada nominalmente no relatório do GAFI/FATF sobre o Brasil (2023), e 85 nas demais. |
| `prismadata__border__score_componente_cidade_gemea` | integer \| null | não | componente D3: 100 se o município possui cidade gêmea, 0 se não. Nulo fora de município de fronteira. |
| `prismadata__border__score_componente_intensidade_municipal` | integer \| null | não | componente D4: combina a fração da área do município dentro da faixa com a presença da sede na faixa. Nulo fora de município de fronteira. |
| `prismadata__border__qtd_fatores_acionados` | integer | sim | quantidade de fatores acionados para o ponto. |
| `prismadata__border__fatores_acionados` | string | sim | fatores acionados, em ordem canônica fixa, separados por `\|`. String vazia quando nenhum fator é acionado. Para filtro e modelagem, prefira os campos booleanos `fator_*`. |
| `prismadata__border__fator_ponto_fora_do_territorio_nacional` | boolean | sim | o ponto está fora do território nacional. É informação de jurisdição e não entra no cálculo do índice. |
| `prismadata__border__fator_ponto_na_faixa` | boolean | sim | o ponto está dentro da faixa de fronteira de 150 km. |
| `prismadata__border__fator_area_influencia_triplice` | boolean | sim | o ponto está a até 50 km de um ponto de tríplice fronteira. |
| `prismadata__border__fator_triplice_iguacu` | boolean | sim | o ponto está na área de influência da Tríplice Fronteira do Iguaçu. |
| `prismadata__border__fator_cidade_gemea` | boolean | sim | o município do ponto possui cidade gêmea no país vizinho. |
| `prismadata__border__fator_municipio_integralmente_na_faixa` | boolean | sim | a área do município está inteiramente dentro da faixa de fronteira. |
| `prismadata__border__fator_sede_na_faixa` | boolean | sim | a sede do município está dentro da faixa de fronteira. |
| `prismadata__border__piso_aplicado` | string \| null | não | rótulo do piso regulatório aplicado, quando ele elevou o índice. `TRIPLICE_FRONTEIRA_GAFI` em áreas de tríplice fronteira. Nulo quando nenhum piso atuou. |

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

---

### `GET /location/border/metadata`

Descreve as fontes de dados, os parâmetros de cálculo e os pontos de tríplice fronteira usados na composição da resposta da API.

**Exemplo curl**:

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

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

> Successful Response

Tipo: `object`.

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

---

## Recursos relacionados

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