# GeoCEP API — Especificação para IAs e Desenvolvedores (llms.txt)
> Base Nacional de Inteligência Geoespacial com 111M+ de Endereços Georreferenciados, Geocodificação Reversa Métrica e Motor de Roteirização Viária e Entregas.

## Informações Gerais
- **Base URL:** `https://geocep.api.br` (ou `http://localhost:8080` em desenvolvimento)
- **Formato:** JSON (`application/json; charset=utf-8`)
- **Autenticação:** Opcional para rotas públicas (100 req/h). Obrigatória para limites contratuais via header `X-API-Key: <chave>` ou `Authorization: Bearer <chave>`.
- **Padrão de Erros:** RFC 7807 Problem Details (`{"status": "error", "code": "...", "message": "..."}`).

---

## 1. Consulta de CEP com Coordenadas Prediais
- **Endpoint:** `GET /v1/cep/{cep}`
- **Parâmetros:**
  - `cep` (obrigatório, path): CEP com 8 dígitos (ex: `66035-170` ou `66035170`).
  - `numero` (opcional, query): Número predial do imóvel para obter a coordenada exata da residência.
- **Exemplo de Chamada:**
  `curl -s "https://geocep.api.br/v1/cep/66035170?numero=1578"`
- **Exemplo de Resposta (200 OK):**
```json
{
  "status": "success",
  "data": {
    "cep": "66035-170",
    "logradouro": "Avenida Nazaré",
    "enderecoCompleto": "Avenida Nazaré, 1578",
    "numero": "1578",
    "bairro": "Nazaré",
    "cidade": "Belém",
    "uf": "PA",
    "codigoIbge": "1501402",
    "ddd": "91",
    "coordenadas": {
      "latitude": -1.452654,
      "longitude": -48.481285,
      "precisao": "numero_exato",
      "fonte": "geocep_core"
    }
  }
}
```

---

## 2. Geocodificação Reversa (GPS para Endereço)
- **Endpoint:** `GET /v1/reverse`
- **Parâmetros:**
  - `lat` (obrigatório, query): Latitude decimal WGS84.
  - `lon` (obrigatório, query): Longitude decimal WGS84.
  - `raio` (opcional, query, padrão: 500): Raio máximo de busca em metros.
- **Exemplo de Chamada:**
  `curl -s "https://geocep.api.br/v1/reverse?lat=-1.452654&lon=-48.481285"`
- **Exemplo de Resposta (200 OK):**
```json
{
  "status": "success",
  "data": {
    "cep": "66035-170",
    "logradouro": "Avenida Nazaré",
    "numero": "1578",
    "bairro": "Nazaré",
    "cidade": "Belém",
    "uf": "PA",
    "codigoIbge": "1501402",
    "distanciaMetros": 0.0,
    "coordenadas": {
      "latitude": -1.452654,
      "longitude": -48.481285
    }
  }
}
```

---

## 3. Autocomplete & Busca Textual
- **Endpoint:** `GET /v1/search`
- **Parâmetros:**
  - `q` (obrigatório, query): Texto do endereço (mínimo 3 caracteres).
  - `uf` (opcional, query): Filtrar por sigla de estado (ex: `PA`, `AP`, `SP`).
  - `limite` (opcional, query, padrão: 10, máx: 20): Quantidade de sugestões.
- **Exemplo de Chamada:**
  `curl -s "https://geocep.api.br/v1/search?q=Nazare%20Belem&uf=PA"`
- **Exemplo de Resposta (200 OK):**
```json
{
  "status": "success",
  "data": [
    {
      "endereco": "Avenida Nazaré, 1578 - Nazaré, Belém - PA",
      "cep": "66035-170",
      "logradouro": "Avenida Nazaré",
      "numero": "1578",
      "bairro": "Nazaré",
      "cidade": "Belém",
      "uf": "PA",
      "latitude": -1.452654,
      "longitude": -48.481285,
      "score": 0.95
    }
  ]
}
```

---

## 4. Otimizador de Rotas Multi-OSs (TSP)
- **Endpoint:** `POST /v1/routes/optimize`
- **Autenticação:** Permite até 25 paradas anônimo; até 500 paradas com API Key.
- **Payload de Entrada:**
```json
{
  "origem": { "endereco": "Avenida Nazaré, 100, Belém - PA" },
  "paradas": [
    { "id_os": "OS-101", "cep": "66035-170", "numero": "1578" },
    { "id_os": "OS-102", "latitude": -1.4550, "longitude": -48.4830 }
  ]
}
```
- **Retorno:** Sequência ótima e natural de visitas (`ordem_otimizada` do ponto mais próximo ao mais próximo até o fim), distância em km, duração em minutos e geometria viária GeoJSON `LineString`.

---

## 5. Crowdsourcing com Consenso Espacial
- **Endpoint:** `POST /v1/contribute` (Requer API Key)
- **Regra de Negócio:** Mediçōes GPS com precisão > 25m retornam `422 INSUFFICIENT_GPS_ACCURACY`. Ao atingir 2 confirmações cruzadas de usuários distintos, o imóvel é promovido para a base oficial e os usuários recebem **+100 créditos de bônus**.

---

## 6. Monitoramento de Cota & Saldo
- **Endpoint:** `GET /v1/usage` (Requer API Key)
- **Retorno:** Cota mensal, requisições consumidas, saldo restante e data de renovação.

---

## 7. Map Tiles Vetoriais & Estilos MapLibre
- **Endpoints:**
  - `GET /v1/maps/style.json`: Folha de estilo pronta compatível com MapLibre GL, Flutter, Leaflet e React Native.
  - `GET /v1/maps/tiles/{z}/{x}/{y}.pbf`: Camadas vetoriais compactadas MVT do OpenStreetMap Brasil.

---

## 8. Níveis de Precisão de Coordenadas
- `numero_exato`: Ponto métrico de porta (< 5m). Retornado quando o número predial consta na base oficial auditada.
- `crowdsourced_consenso`: Ponto validado com consenso de operadores em campo (< 10m).
- `rua_interpolada`: Ponto no eixo viário próximo à numeração (< 25m). Evita erros 404 quando o número específico ainda não foi catalogado individualmente.
- `centroide`: Ponto médio do logradouro (~100m). Retornado em consultas apenas por CEP sem número.
- `coordenada_direta`: Coordenada GPS bruta informada pelo cliente.