FlowData

Como buscar lugares e endereços com o Maps?

Publicado em 10. novembro 2026

A busca de lugares do Maps encontra endereços, ruas, códigos postais e lugares a partir de um termo. Ela serve, por exemplo, para autocompletar endereços em um formulário de pedido ou padronizar o que seus clientes digitam. Você recebe até dez resultados com coordenadas e as partes do endereço bem separadas.

A requisição

A busca é um GET para https://api.flowdata.one/v1/maps/search. Apenas o termo de busca q é obrigatório.

curl "https://api.flowdata.one/v1/maps/search?q=Alexanderplatz%201%20Berlin&limit=5&country=DE&language=pt" \
  -H "Authorization: Bearer fd_SUA_CHAVE"

Você pode enviar estes parâmetros:

Parâmetro Significado
q Termo de busca, obrigatório, no máximo 256 caracteres. Codificado para URL, ou seja, espaços como %20.
limit Número de resultados de 1 a 10. O padrão é 10.
country Código de país de duas letras como BR, PT ou DE. Limita a busca a esse país.
language Idioma dos nomes. O padrão é de.
proximity Um ponto como longitude,latitude, por exemplo 13.4050,52.5200. Resultados próximos têm preferência.
types Limita o tipo de resultado, por exemplo address, street, postcode ou place. Separe vários valores com vírgula.

Para autocompletar, em geral bastam q, limit=5 e country=BR.

A resposta

{
  "success": true,
  "addresses": [
    {
      "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",
      "region_name": "Berlin",
      "region_code": "BE",
      "country_name": "Alemanha",
      "country_code": "DE"
    }
  ],
  "attribution": "NOTICE: © 2026 ... This response and the information it contains may not be retained."
}

O exemplo está resumido; em geral addresses traz vários resultados. Cada resultado tem estes campos:

  • lat, lng: latitude e longitude.
  • full_address: o endereço completo e legível para exibição.
  • address_name: rua com número.
  • street_name, address_number: rua e número separados.
  • postcode_name: código postal.
  • locality_name: bairro, se conhecido.
  • place_name: cidade ou município.
  • region_name, region_code: estado e sua sigla.
  • country_name, country_code: país e código de duas letras.

Campos que não existem para um resultado vêm como null. Um código postal como resultado, por exemplo, não tem rua.

Em que ordem vêm os resultados?

O Maps ordena os resultados pela completude. Primeiro vêm os endereços completos com rua, número, código postal, cidade e país. Depois, ruas sem número, em seguida códigos postais com cidade, depois apenas cidades e, por fim, resultados em que só o país é conhecido. Em um formulário de endereço, o primeiro resultado costuma ser, portanto, o mais adequado.

Se não houver resultado, você recebe mesmo assim "success": true, mas com a lista addresses vazia.

O que significa o texto de attribution?

Toda resposta bem-sucedida traz um aviso de uso no campo attribution. Ele diz que os dados estão sujeitos aos termos de uso e que a resposta não pode ser armazenada de forma permanente. Portanto, mostre os resultados diretamente ou leve para o pedido o endereço que sua cliente escolher. Montar uma base de endereços própria a partir dos resultados não é permitido.

Quando algo dá errado

Se q estiver faltando ou um parâmetro for inválido, o Maps responde com HTTP 422. Em details aparece qual campo tem o problema:

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

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

Outros problemas comuns, como coordenadas invertidas, estão em O Maps não encontra nada ou mostra o lugar errado: o que fazer?.

Quanto custa uma busca?

A busca de lugares é cobrada a cada 1.000 requisições bem-sucedidas. Uma busca só conta se retornar pelo menos um resultado. Uma busca com lista vazia e todos os erros são gratuitos. Respostas vindas do cache contam como qualquer outra resposta bem-sucedida.

Os valores estão na página de preços, e os preços válidos para sua equipe ficam no painel, em Cobrança. Se o saldo não for suficiente, a API responde com HTTP 402. Saiba mais em Entender os preços do FlowData.

Bom saber

  • Para ver quantas requisições sua integração faz e quantas falham, acesse Áreas › Maps no painel. Logo abaixo fica o Registro com cada requisição.
  • Se você só precisa das coordenadas de um endereço conhecido, a geocodificação é o caminho mais direto; veja Como converter um endereço em coordenadas e vice-versa?.
  • Envie a busca do seu servidor. Para autocompletar no navegador, crie um pequeno endpoint próprio que repasse o texto ao Maps, para que a chave não vá parar no navegador.
  • A referência completa está na documentação da API.

Este artigo foi útil?

Voltar para Maps