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.