# GeoCEP API — Especificação Técnica Exaustiva (llms-full.txt) > Documento técnico completo de referência com contratos JSON, schemas, códigos de erro RFC 7807 e exemplos de integração em múltiplas linguagens. ## Índice 1. Visão Geral da Arquitetura e Protocolos 2. Autenticação, Cabeçalhos e Rate Limiting 3. Especificação Completa dos Endpoints 3.1. GET /v1/cep/{cep} 3.2. GET /v1/reverse 3.3. GET /v1/search 3.4. POST /v1/routes/optimize 3.5. POST /v1/contribute 3.6. GET /v1/usage 4. Catálogo de Erros RFC 7807 Problem Details 5. Exemplos de Integração de Código (cURL, Python, Node.js, PHP) --- ## 1. Visão Geral da Arquitetura e Protocolos - **Protocolo:** HTTPS / TLS 1.3 - **Codificação:** UTF-8 - **Identificadores:** UUID versão 7 ordenados cronologicamente - **Projeção Cartográfica:** WGS84 (EPSG:4326) - **Base de Dados:** 111M+ de endereços georreferenciados em território nacional com indexação espacial particionada por UF. --- ## 2. Autenticação e Rate Limiting ### Cabeçalhos Suportados: - `X-API-Key: ` - `Authorization: Bearer ` ### Regras de Rate Limiting (Token Bucket Atômico em Memória): - **Usuários Anônimos:** 100 requisições / hora por IP. - **Plano Gratuito:** 3.000 requisições / mês. - **Plano Starter:** 30.000 requisições / mês. - **Plano Pro:** 300.000 requisições / mês. ### Cabeçalhos de Resposta de Rate Limit: - `X-RateLimit-Limit`: Limite máximo da janela. - `X-RateLimit-Remaining`: Requisições restantes. - `X-RateLimit-Reset`: Timestamp Unix da renovação da cota. --- ## 3. Especificação Completa dos Endpoints ### 3.1. GET /v1/cep/{cep} Consulta de dados cadastrais e coordenadas de um CEP com resolução predial opcional. #### Parâmetros: | Parâmetro | Tipo | Local | Obrigatório | Descrição | |---|---|---|---|---| | `cep` | string | Path | Sim | CEP com ou sem hífen (8 dígitos). | | `numero` | string | Query | Não | Número da residência ou prédio para retornar coordenadas exatas. | #### Resposta de Sucesso (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": "ibge_cnefe" } } } ``` --- ### 3.2. GET /v1/reverse Converte coordenadas GPS (latitude e longitude) no endereço e CEP mais próximo. #### Parâmetros: | Parâmetro | Tipo | Local | Obrigatório | Descrição | |---|---|---|---|---| | `lat` | number | Query | Sim | Latitude decimal (-90 a 90). | | `lon` | number | Query | Sim | Longitude decimal (-180 a 180). | | `raio` | number | Query | Não | Raio máximo de busca em metros (Padrão: 500, Máx: 5000). | --- ### 3.3. GET /v1/search Busca textual e autocomplete instantâneo para caixas de checkout e cadastros. #### Parâmetros: | Parâmetro | Tipo | Local | Obrigatório | Descrição | |---|---|---|---|---| | `q` | string | Query | Sim | Termo de busca (mínimo 3 caracteres). | | `uf` | string | Query | Não | Filtro por sigla de estado (ex: `PA`, `SP`, `RJ`). | | `limite` | integer | Query | Não | Limite de resultados (Padrão: 10, Máx: 20). | --- ### 3.4. POST /v1/routes/optimize Otimização de trajeto viário real e sequenciamento de visitas (Caixeiro Viajante - TSP). #### Limites: - **Anônimo:** Até 25 paradas. - **Autenticado com API Key:** Até 500 paradas. #### 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 } ] } ``` #### Payload de Resposta (200 OK): ```json { "status": "success", "data": { "resumo": { "total_paradas": 2, "distancia_total_km": 4.25, "duracao_total_minutos": 12.8 }, "ordem_otimizada": [ { "posicao": 1, "id_referencia": "OS-101", "endereco": "Avenida Nazaré, 1578", "distancia_trecho_km": 1.2, "tempo_trecho_min": 3.5 }, { "posicao": 2, "id_referencia": "OS-102", "endereco": "Travessa Rui Barbosa, 200", "distancia_trecho_km": 3.05, "tempo_trecho_min": 9.3 } ], "geometria_geojson": { "type": "LineString", "coordinates": [[-48.4812, -1.4526], [-48.4830, -1.4550]] } } } ``` --- ### 3.5. POST /v1/contribute Ingestão colaborativa de coordenadas de campo com consenso espacial. #### Requisito de Precisão GPS: - `precisao_gps_metros <= 25.0`. Caso contrário, retorna `422 INSUFFICIENT_GPS_ACCURACY`. #### Recompensa: - Concede **+100 créditos** na conta do colaborador assim que o imóvel obtiver 2 confirmações independentes. ### 3.6. GET /v1/maps/style.json & GET /v1/maps/tiles/{z}/{x}/{y}.pbf Entrega folhas de estilo e camadas vetoriais compactadas MVT do OpenStreetMap Brasil para renderização gráfica em MapLibre GL, Flutter, Leaflet e React Native. --- ## 4. Catálogo de Erros RFC 7807 Problem Details | Código HTTP | Código RFC 7807 | Descrição | |---|---|---| | `400 Bad Request` | `INVALID_REQUEST` | CEP inválido ou campos obrigatórios ausentes. | | `401 Unauthorized` | `UNAUTHORIZED_ACCESS` | API Key ausente, inválida ou revogada. | | `404 Not Found` | `CEP_NOT_FOUND` | CEP inexistente na base de dados oficial. | | `422 Unprocessable Entity` | `INSUFFICIENT_GPS_ACCURACY` | Precisão do GPS acima de 25 metros. | | `429 Too Many Requests` | `RATE_LIMIT_EXCEEDED` | Limite de requisições por hora/mês atingido. | | `500 Internal Server Error` | `INTERNAL_SERVER_ERROR` | Falha inesperada no processamento interno. | --- ## 5. Exemplos de Código ### 5.1. cURL ```bash curl -X GET "https://geocep.api.br/v1/cep/66035170?numero=1578" \ -H "X-API-Key: gc_live_sua_chave" ``` ### 5.2. Python (requests) ```python import requests url = "https://geocep.api.br/v1/cep/66035170" headers = {"X-API-Key": "gc_live_sua_chave"} params = {"numero": "1578"} response = requests.get(url, headers=headers, params=params) data = response.json() if response.status_code == 200: coords = data["data"]["coordenadas"] print(f"Latitude: {coords['latitude']}, Longitude: {coords['longitude']}") else: print(f"Erro: {data.get('message')}") ``` ### 5.3. Node.js (fetch / Axios) ```javascript const apiKey = 'gc_live_sua_chave'; const cep = '66035170'; async function buscarEndereco() { const response = await fetch(`https://geocep.api.br/v1/cep/${cep}?numero=1578`, { headers: { 'X-API-Key': apiKey } }); const result = await response.json(); console.log(result.data); } buscarEndereco(); ``` ### 5.4. PHP ```php ``` --- ## 6. Níveis de Precisão de Coordenadas & Resolução Espacial Todo payload retornado com geolocalização acompanha os campos `precisao` e `fonte`. ### Classificação do campo `precisao`: 1. **`numero_exato`** (Resolução Métrica < 5m): - Coordenada na porta de entrada do lote ou edifício. Retornado quando a consulta especifica o `numero` e ele consta na Base Nacional oficial ou foi auditado em campo. 2. **`crowdsourced_consenso`** (Resolução Auditada < 10m): - Ponto de entrega validado por múltiplos motoristas/entregadores em campo via algoritmo de triangulação espacial. 3. **`rua_interpolada`** (Resolução Eixo Viário < 25m): - Ponto no eixo do logradouro próximo à numeração solicitada. Utilizado quando o número específico ainda não possui ponto métrico individual cadastrado, garantindo alta disponibilidade (zero 404). 4. **`centroide`** (Resolução Área ~100m): - Centroide médio do logradouro ou zona postal. Retornado sempre que a consulta é feita apenas pelo CEP sem informar o número predial. 5. **`coordenada_direta`**: - Ponto GPS bruto enviado diretamente pelo cliente no payload da requisição. ### Classificação do campo `fonte`: - `ibge_cnefe`: Base Nacional Oficial de Endereços Auditados. - `crowdsourcing`: Ponto validado com consenso de campo colaborativo. - `usuario_gps`: Coordenada fornecida diretamente pela aplicação cliente. - `osm`: Malha viária do OpenStreetMap.