# Geocoder > API de geocodificação de endereços brasileiros. Converte endereços em coordenadas GPS (geocodificação direta) e coordenadas em endereços (geocodificação reversa). **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____`; em lote, dicionário indexado pelas chaves enviadas. Detalhes em [Formato de Resposta](guias/formato-de-resposta.md). ## Endpoints ### `GET /location/geocoder` Endpoint para se obter a latitude e longitude de um endereço. Há duas formas de se realizar a geocodificação: 1. Fornecendo o endereço completo em uma única string (endereco_completo). 2. Fornecendo os campos do endereço de forma individualizada. Caso o endereço completo seja fornecido, ele é quebrado nos campos internamente e se os campos forém fornecidos também, estes têm preferência sobre os campos extraídos do endereço completo. Por isso, sugere-se que, se possível, a geocodificação seja feita pelos campos individualizados e não pelo endereço completo. **Exemplo curl**: ```bash curl -X GET "https://api.prismadata.io/v1/location/geocoder" \ -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 | |------|-------|------|-------------|-----------| | `endereco_completo` | query | string \| null | não | Endereço completo a ser 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 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__geocoder__cep` | string | sim | CEP da coordenada do endereço geocodificado | | `prismadata__geocoder__cod_setor_cnefe` | string \| null | não | Código do setor censitário IBGE 2022 (15 dígitos) do endereço geocodificado. `null` para os ~2% de endereços sem correção CNEFE-Faces. | | `prismadata__geocoder__classificacao_qualidade_geocodificacao` | string | sim | 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. | | `prismadata__geocoder__endereco_completo` | string | sim | Endereço completo da coordenada geocodificada | | `prismadata__geocoder__latitude` | number | sim | Latitude da coordenada do endereço geocodificado. | | `prismadata__geocoder__localidade` | string | sim | Nome da localidade da coordenada geocodificada. Frequentemente é o nome do bairro ou da região. | | `prismadata__geocoder__logradouro` | string | sim | Logradouro da coordenada geocodificada. | | `prismadata__geocoder__longitude` | number | sim | Longitude da coordenada do endereço geocodificado. | | `prismadata__geocoder__municipio` | string | sim | Nome do município em que se encontra a coordenada geocodificada. | | `prismadata__geocoder__numero` | integer | sim | Número da coordenada no endereço geocodificado | | `prismadata__geocoder__score_qualidade_geocodificacao` | number | sim | Número que indica o quão confiável é a geocodificação. Varia em uma escala de 0 a 100, onde o valor 100 indica qualdiade máxima. | | `prismadata__geocoder__uf` | string | sim | Sigla da unidade federativa em que se encontra a coordenada geocodificada. | **Outros códigos**: 401, 403, 422, 429 --- ### `GET /location/reverse_geocoder` Realiza a geocodificação reversa de um ponto, isto é, retorna o endereço de uma latitude e longitude. Se não for encontrado um endereço próximo ao ponto, retorna um objeto vazio. **Exemplo curl**: ```bash curl -X GET "https://api.prismadata.io/v1/location/reverse_geocoder?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 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 | **Response 200** (`application/json`): > Successful Response | Campo | Tipo | Obrigatório | Descrição | |-------|------|-------------|-----------| | `prismadata__reverse_geocoder__cep` | string | sim | CEP do endereço mais próximo da coordenada a ser geocodificada reversamente. | | `prismadata__reverse_geocoder__distancia_m` | number | sim | Distância geodésica, em metros, entre a coordenada de entrada e do endereço geocodificado reversamente. | | `prismadata__reverse_geocoder__endereco_completo` | string | sim | Endereço completo da coordenada resultante geocodificação reversa. | | `prismadata__reverse_geocoder__latitude_endereco` | number | sim | Latitude da coordenada do endereço resutltado da geocodificação reversa. | | `prismadata__reverse_geocoder__latitude_input` | number | sim | Latitude da coordenada de entrada da geocodificação reversa. | | `prismadata__reverse_geocoder__localidade` | string | sim | Localidade (frequentemente bairro ou região) da coordenada resultante geocodificação reversa. | | `prismadata__reverse_geocoder__logradouro` | string | sim | Logradouro da coordenada resultante geocodificação reversa. | | `prismadata__reverse_geocoder__longitude_endereco` | number | sim | Longitude da coordenada do endereço resutltado da geocodificação reversa. | | `prismadata__reverse_geocoder__longitude_input` | number | sim | Longitude da coordenada de entrada da geocodificação reversa. | | `prismadata__reverse_geocoder__municipio` | string | sim | Municipio da coordenada resultante geocodificação reversa. | | `prismadata__reverse_geocoder__cod_municipio` | integer \| null | não | Código IBGE do município (7 dígitos: UF+MUN), derivado do setor censitário CNEFE do endereço mais próximo. Chave canônica para cruzar com renda, CNPJ e denominador municipal (dompp_municipio_batch) do programa Entorno. `null` para os ~2% de endereços sem correção CNEFE-Faces. | | `prismadata__reverse_geocoder__numero` | integer | sim | Número no logradouro da coordenada resultante geocodificação reversa. | | `prismadata__reverse_geocoder__uf` | string | sim | Sigla da unidade federativa da coordenada resultante geocodificação reversa. | **Outros códigos**: 401, 403, 422, 429 --- ### `POST /location/batch/geocoder` Endpoint para geocodificacao em batch. Recebe um dict de ate 512 enderecos indexados por chaves definidas pelo cliente e retorna as coordenadas de cada um, preservando as mesmas chaves na resposta. **Exemplo curl**: ```bash curl -X POST "https://api.prismadata.io/v1/location/batch/geocoder" \ -H "X-Apikey: SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "1": { "endereco_completo": "Rua Alagoas 686, Belo Horizonte MG" }, "2": { "cep": "30130-165", "numero": 601, "logradouro": "Alagoas", "municipio": "Belo Horizonte", "estado": "MG" } }' ``` **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.
Exemplo ```json { "1": { "endereco_completo": "Rua Alagoas 686, Belo Horizonte MG" }, "2": { "cep": "30130-165", "numero": 601, "logradouro": "Alagoas", "municipio": "Belo Horizonte", "estado": "MG" } } ```
**Response 200** (`application/json`): > Successful Response Dicionário `{string: object}`. Dict indexado pelas chaves enviadas pelo cliente. Cada valor contém os campos do geocoder com prefixo prismadata__geocoder__. **Outros códigos**: 401, 403, 422, 429 --- ### `POST /location/batch/reverse_geocoder` Endpoint para geocodificacao reversa em batch. Recebe um dict de ate 1024 coordenadas indexadas por chaves definidas pelo cliente e retorna o endereco mais proximo de cada uma, preservando as mesmas chaves na resposta. **Exemplo curl**: ```bash curl -X POST "https://api.prismadata.io/v1/location/batch/reverse_geocoder" \ -H "X-Apikey: SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "1": { "lat": -19.932, "lng": -43.938 }, "2": { "lat": -23.5614, "lng": -46.6559 } }' ``` **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.
Exemplo ```json { "1": { "lat": -19.932, "lng": -43.938 }, "2": { "lat": -23.5614, "lng": -46.6559 } } ```
**Response 200** (`application/json`): > Successful Response Dicionário `{string: object}`. Dict indexado pelas chaves enviadas pelo cliente. Cada valor contém os campos do reverse geocoder com prefixo prismadata__reverse_geocoder__. **Outros códigos**: 401, 403, 422, 429 --- ## Recursos relacionados - Documentação Redoc interativa: https://prismadata.io/redoc.html#tag/Geocoder - OpenAPI só deste produto (JSON): https://prismadata.io/llm/openapi/geocoder.json - OpenAPI completo: https://prismadata.io/openapi.yaml - Índice geral: https://prismadata.io/llms.txt