FlowData

Como converter um endereço em coordenadas e vice-versa?

Publicado em 10. novembro 2026

A geocodificação converte um endereço em coordenadas, por exemplo para mostrar endereços de clientes em um mapa ou calcular distâncias. Já a geocodificação reversa encontra o endereço de um ponto, como a localização GPS de um aplicativo. As duas usam o mesmo endpoint e retornam exatamente um resultado, o melhor.

Converter um endereço em coordenadas

Envie o endereço no parâmetro address, com no máximo 256 caracteres. Opcionalmente, restrinja a um país com country e escolha o idioma dos nomes com language (padrão de).

curl "https://api.flowdata.one/v1/maps/geocode?address=Alexanderplatz%201,%2010178%20Berlin&country=DE&language=pt" \
  -H "Authorization: Bearer fd_SUA_CHAVE"

O campo address da resposta traz exatamente um resultado:

{
  "success": true,
  "address": {
    "lat": 52.521918,
    "lng": 13.413215,
    "full_address": "Alexanderplatz 1, 10178 Berlin, Alemanha",
    "address_name": "Alexanderplatz 1",
    "address_number": "1",
    "street_name": "Alexanderplatz",
    "postcode_name": "10178",
    "locality_name": "Mitte",
    "place_name": "Berlin",
    "place_code": "BE",
    "region_name": "Berlin",
    "region_code": "BE",
    "country_name": "Alemanha",
    "country_code": "DE"
  },
  "attribution": "NOTICE: © 2026 ..."
}

Os campos são os mesmos da busca de lugares, mais place_code, uma sigla do lugar. O significado de todos os campos está em Como buscar lugares e endereços com o Maps?.

Converter coordenadas em um endereço

Para o caminho inverso, envie os parâmetros lat (latitude, de -90 a 90) e lng (longitude, de -180 a 180) em vez de address. Assim que os dois forem informados, o endpoint funciona ao contrário.

curl "https://api.flowdata.one/v1/maps/geocode?lat=52.5219&lng=13.4132" \
  -H "Authorization: Bearer fd_SUA_CHAVE"

A resposta tem o mesmo formato acima, com o endereço mais próximo do ponto.

Quando nada é encontrado

Se o Maps não encontrar um endereço adequado, ele retorna HTTP 404:

{"success":false,"error":"No address data found for this address"}

Na geocodificação reversa, o texto é No address found for the specified coordinates. As causas mais comuns são erros de digitação, código postal ausente, código de país errado ou coordenadas que apontam para água ou área aberta.

Se address, lat e lng estiverem todos ausentes, ou se você enviar só uma das duas coordenadas, o Maps responde com HTTP 422 e lista os campos afetados em details:

{"success":false,"error":"Invalid parameters","details":{"address":["..."]}}

A chave em details é o nome do campo; o texto da mensagem está em alemão no momento.

Por que recebo um endereço vizinho?

O Maps guarda endereços já determinados para responder mais rápido a requisições repetidas. Na geocodificação reversa, pode voltar um endereço já conhecido muito próximo, como a casa ao lado. Para mapas, isso costuma ser suficiente. Se você precisa do número exato, peça à pessoa que confirme o endereço.

Pelo mesmo motivo, os nomes podem vir em um idioma diferente do informado em language, se o endereço já tiver sido determinado antes nesse outro idioma.

Por que entradas curtas não dão o resultado certo?

A geocodificação foi feita para endereços completos. Com entradas muito curtas ou genéricas, como "Berlin" ou "Rua Principal", pode voltar qualquer resultado que contenha o termo, por exemplo um endereço qualquer de rua em Berlim. Para ter resultados confiáveis:

  1. Informe rua, número, código postal e cidade.
  2. Defina country se você souber o país.
  3. Para termos de busca, nomes de lugares e autocompletar, use a busca de lugares. Ela retorna vários resultados para você escolher.

Quanto custa uma requisição?

A geocodificação é cobrada a cada 1.000 requisições bem-sucedidas, com o mesmo preço nas duas direções. Respostas com HTTP 404 ou 422 e erros de servidor são gratuitas. Os valores estão na página de preços, e os detalhes em Entender os preços do FlowData.

Bom saber

  • Atenção aos nomes: a geocodificação usa os parâmetros separados lat e lng. No cálculo de rotas, as coordenadas vão em um único valor como longitude,latitude; veja Como calcular uma rota com o Maps?.
  • A resposta traz um aviso de uso no campo attribution. Os dados não podem ser armazenados de forma permanente.

Este artigo foi útil?

Voltar para Maps