API › Location › Geocoder # Geocoder Geocodificação direta e reversa especializada no Brasil. Converte endereços em coordenadas e coordenadas em endereços, com score de qualidade e cobertura nacional. Passo inicial para todos os demais dados de Location da PrismaData. Categoria Location Cobertura Brasil — todo o território Modos Direto + Reverso Fonte IBGE + OSM + Overture Maps Atualização Mensal Nesta página Aplicações Conceito Geocoder Direto Entradas Atributos Geocoder Reverso Entradas Atributos Exemplos Detalhes técnicos Limitações Para que serve ## Aplicações O geocoder é a ponte entre endereços textuais e coordenadas geográficas. É frequentemente o passo inicial para acessar os demais dados de Location da PrismaData (renda, favelas, presídios, fronteira, setor censitário) — que recebem latitude e longitude como entrada. #### Enriquecimento de Base Converta endereços cadastrais em coordenadas para alimentar APIs de renda, risco territorial, favelas e presídios — sem dependência de geocoders genéricos. #### Validação Cadastral Verifique se o endereço declarado pelo cliente existe e retorna coordenadas válidas. O score de qualidade indica o grau de confiança na geocodificação. #### Geocodificação Reversa Transforme coordenadas de GPS, dispositivos ou eventos em endereço completo — útil para rastreamento, logística e associação de eventos a localidades. #### Padronização de Endereços O retorno normaliza logradouro, bairro, município, UF e CEP em formato padronizado — reduzindo inconsistências de bases cadastrais legadas. Entendendo o dado ## Conceito O Geocoder da PrismaData é especializado no Brasil — não depende de provedores genéricos globais. Opera em dois modos complementares: Direto #### Endereço → Coordenada Recebe componentes de endereço (logradouro, número, bairro, município, UF, CEP) e retorna latitude, longitude, endereço normalizado e score de qualidade de 0 a 100. Rua Alagoas, 601, BH → -19.9326, -43.9354 Reverso #### Coordenada → Endereço Recebe latitude e longitude e retorna o endereço mais próximo, com a distância em metros entre a coordenada de entrada e o ponto do endereço encontrado. -22.9863, -43.2088 → Av. Vieira Souto, 516, RJ O geocoder é frequentemente o primeiro passo para consumir os demais dados de Location da PrismaData. A coordenada retornada pelo geocoder direto pode ser usada como entrada para as APIs de Renda, Favelas, Presídios, Fronteira e Setor Censitário. Modo 1 ## Geocoder Direto Converte um endereço textual em coordenadas geográficas. Aceita o endereço completo ou campos separados. ### Parâmetros de Entrada endereco_completo Endereço completo como string única. Alternativa ao envio de campos separados. string logradouro Nome do logradouro (ex: "Alagoas", "Vieira Souto"). string tipo_logradouro Tipo do logradouro: Rua, Avenida, Travessa, Praça, etc. string titulo_logradouro Título do logradouro: Dr., Coronel, São, Dona, etc. string numero Número do endereço. string ou int localidade Bairro ou região do endereço. string municipio Nome do município. string estado Sigla ou nome da unidade federativa (ex.: `MG`, `SP`, `RJ`). string cep CEP do endereço (Código de Endereçamento Postal). string ### Atributos Retornados Coordenadas latitude Latitude do endereço geocodificado. longitude Longitude do endereço geocodificado. Endereço Normalizado endereco_completo Endereço completo normalizado, composto pela concatenação dos demais campos. logradouro Nome do logradouro normalizado. numero Número do endereço. localidade Bairro ou região normalizada. municipio Nome do município. uf Sigla da unidade federativa. cep CEP do endereço geocodificado. Qualidade score_qualidade_geocodificacao Score numérico de 0 a 100 indicando a confiança na geocodificação. Valores mais altos = maior confiança. classificacao_qualidade_geocodificacao Classificação categórica: `MUITO_ALTA`, `ALTA`, `MEDIA`, `BAIXA` ou `MUITO_BAIXA`. Modo 2 ## Geocoder Reverso Converte coordenadas geográficas no endereço mais próximo, com a distância em metros entre o ponto de entrada e o endereço encontrado. ### Parâmetros de Entrada `lat` float Latitude WGS84 da coordenada a geocodificar reversamente. `lng` float Longitude WGS84 da coordenada a geocodificar reversamente. ### Atributos Retornados Endereço Encontrado endereco_completo Endereço completo mais próximo da coordenada de entrada. logradouro Nome do logradouro do endereço encontrado. numero Número do endereço encontrado. localidade Bairro ou região do endereço encontrado. municipio Município do endereço encontrado. cod_municipio Código IBGE de 7 dígitos do município do endereço encontrado. uf Sigla da unidade federativa. cep CEP do endereço encontrado. Coordenadas latitude_input Latitude fornecida como entrada (eco do input). longitude_input Longitude fornecida como entrada (eco do input). latitude_endereco Latitude do endereço mais próximo encontrado. longitude_endereco Longitude do endereço mais próximo encontrado. Metadados distancia_m Distância em metros entre a coordenada de entrada e o ponto do endereço encontrado. Na prática ## Exemplos Dois cenários reais ilustram os dois modos do geocoder: direto (endereço → coordenada) e reverso (coordenada → endereço). Geocodificação direta — Sede PrismaData, BH Direto Rua Alagoas, 601, Savassi — Belo Horizonte — MG — 30130-165 _[Imagem: Mapa: geocodificação direta — Rua Alagoas, 601, Savassi, BH]_ { "prismadata__geocoder__cep": "30130-160", "prismadata__geocoder__classificacao_qualidade_geocodificacao": "MUITO_ALTA", "prismadata__geocoder__endereco_completo": "RUA ALAGOAS, 601 - SAVASSI, BELO HORIZONTE - MG, 30130-160", "prismadata__geocoder__latitude": -19.932592391967773, "prismadata__geocoder__localidade": "SAVASSI", "prismadata__geocoder__logradouro": "RUA ALAGOAS", "prismadata__geocoder__longitude": -43.93540573120117, "prismadata__geocoder__municipio": "BELO HORIZONTE", "prismadata__geocoder__numero": 601, "prismadata__geocoder__score_qualidade_geocodificacao": 100.0, "prismadata__geocoder__uf": "MG" } Endereço geocodificado com score 100 — MUITO ALTA. A coordenada retornada (-19.9326, -43.9354) corresponde ao endereço exato da sede da PrismaData na Savassi. O retorno normaliza os componentes do endereço em campos separados e padronizados. Geocodificação reversa — Ipanema, RJ Reverso latitude = -22.98627572993613 | longitude = -43.208798617447684 _[Imagem: Mapa: geocodificação reversa — Ipanema, RJ]_ { "prismadata__reverse_geocoder__cep": "22420-008", "prismadata__reverse_geocoder__distancia_m": 7.02674626, "prismadata__reverse_geocoder__endereco_completo": "AVENIDA VIEIRA SOUTO, 516 - IPANEMA, RIO DE JANEIRO - RJ, 22420-008", "prismadata__reverse_geocoder__latitude_endereco": -22.986234664916992, "prismadata__reverse_geocoder__latitude_input": -22.98627572993613, "prismadata__reverse_geocoder__localidade": "IPANEMA", "prismadata__reverse_geocoder__logradouro": "AVENIDA VIEIRA SOUTO", "prismadata__reverse_geocoder__longitude_endereco": -43.2088508605957, "prismadata__reverse_geocoder__longitude_input": -43.208798617447684, "prismadata__reverse_geocoder__municipio": "RIO DE JANEIRO", "prismadata__reverse_geocoder__numero": 516, "prismadata__reverse_geocoder__uf": "RJ" } A coordenada de entrada foi resolvida para Av. Vieira Souto, 516 — Ipanema, RJ. A distância entre o ponto informado e o endereço encontrado é de apenas **7,03 metros**. O retorno inclui tanto as coordenadas de entrada (input) quanto as do endereço encontrado, permitindo calcular e verificar a precisão da resolução. Referência ## Detalhes Técnicos #### Fontes * IBGE — Malha de endereços e logradouros * OpenStreetMap (OSM) * Overture Maps * Processamento e agregação PrismaData #### Cobertura Exclusivamente Brasil — todo o território nacional. Endereços ou coordenadas fora do Brasil não são suportados. A cobertura é maior em áreas urbanas e pode ser limitada em regiões rurais remotas ou loteamentos muito recentes. #### Atualização * Base de endereços: mensal * Algoritmo de geocodificação: atualizado continuamente #### Metodologia Agregação de múltiplas bases de endereços (IBGE, OSM, Overture Maps) com metodologia proprietária PrismaData para matching, normalização e resolução de coordenadas. Score de qualidade calculado com base no nível de correspondência entre entrada e base. Atenção ## Limitações #### Considere ao utilizar * O geocoder opera exclusivamente no Brasil. Endereços ou coordenadas fora do território nacional não são suportados. * Não há garantia de que toda geocodificação será bem-sucedida. Bases cadastrais podem conter endereços inconsistentes, desatualizados ou com grafia divergente das fontes de referência. Use o `score_qualidade_geocodificacao` para avaliar a confiabilidade do resultado. * Loteamentos muito recentes, áreas rurais remotas ou ocupações informais podem ter cobertura limitada nas bases de referência. * O geocoder reverso retorna o endereço mais próximo da coordenada informada. Em áreas de baixa densidade de endereços, a distância (`distancia_m`) pode ser grande — avalie este campo para decidir se o resultado é aceitável. * O campo `classificacao_qualidade_geocodificacao` está disponível apenas no geocoder direto. O reverso retorna `distancia_m` como proxy de qualidade. ## Pronto para testar? Solicite acesso à sandbox do Geocoder e converta seus endereços em coordenadas — ou vice-versa. [ Solicitar acesso ]()