O endpoint de rotas do Maps calcula distância e tempo de viagem entre dois ou mais pontos. Isso ajuda em custos de deslocamento em orçamentos, áreas de entrega ou no planejamento de roteiros da equipe externa. Você recebe a distância, a duração, o traçado da rota e as indicações de cada trecho.
A requisição
A rota é um GET para https://api.flowdata.one/v1/maps/directions. Início (origin) e destino (destination) são obrigatórios, cada um como longitude,latitude, ou seja, a longitude vem primeiro.
curl "https://api.flowdata.one/v1/maps/directions?origin=13.4050,52.5200&destination=13.7373,51.0504&profile=driving&language=pt" \
-H "Authorization: Bearer fd_SUA_CHAVE"
O exemplo calcula uma viagem de carro de Berlim a Dresden. Para obter as coordenadas de um endereço, use a geocodificação; veja Como converter um endereço em coordenadas e vice-versa?.
Todos os parâmetros
| Parâmetro | Significado |
|---|---|
origin |
Ponto de partida como longitude,latitude, obrigatório. |
destination |
Destino como longitude,latitude, obrigatório. |
waypoints |
Paradas no caminho, separadas por uma barra vertical |, por exemplo 12.3731,51.3397|11.5820,50.9271. Em uma URL, escreva como %7C. |
profile |
Meio de transporte: driving-traffic (carro com trânsito atual, padrão), driving (carro), walking (a pé) ou cycling (bicicleta). |
alternatives |
1 retorna também rotas alternativas, quando possível. Use 1, não true. |
avoid |
Tipos de via a evitar, por exemplo motorway, toll ou ferry. Separe vários valores com vírgula. |
language |
Idioma das instruções. O padrão é de. |
Se você não informar profile, o Maps calcula com driving-traffic, ou seja, de carro considerando o trânsito atual. As indicações de cada trecho sempre vêm na resposta; não é preciso ativá-las.
A resposta
{
"success": true,
"routes": [
{
"distance": 193412.6,
"duration": 7380.4,
"geometry": {"type": "LineString", "coordinates": [[13.405, 52.52], [13.4061, 52.5183], "..."]},
"legs": [
{
"distance": 193412.6,
"duration": 7380.4,
"summary": "A 13",
"steps": [
{
"distance": 412.3,
"duration": 61.2,
"geometry": {"type": "LineString", "coordinates": ["..."]},
"instruction": "Siga para o sul na Spandauer Straße.",
"maneuver": {"type": "depart", "modifier": null, "location": [13.405, 52.52]}
}
]
}
],
"summary": "",
"weight": 7811.9
}
],
"waypoints": [
{"name": "Spandauer Straße", "location": [13.405, 52.52]},
{"name": "Wilsdruffer Straße", "location": [13.7373, 51.0504]}
],
"attribution": "NOTICE: © 2026 ..."
}
Os valores do exemplo estão resumidos e são fictícios. Como ler os campos:
- distance: distância em metros, então
193412.6são pouco mais de 193 quilômetros. - duration: tempo de viagem em segundos, então
7380.4são cerca de duas horas e três minutos. - routes: a rota, ou várias com
alternatives=1. A primeira é a recomendada. - legs: um trecho por parte do percurso. Sem paradas há um trecho; com duas paradas, três.
- steps: as instruções individuais de condução, com o texto em
instructione a manobra. - geometry: o traçado da rota como linha GeoJSON (
LineString) para desenhar em um mapa. Aqui também os pontos vêm como[longitude, latitude]. - waypoints: início, paradas e destino, como o Maps os posicionou na malha viária.
Quando algo dá errado
- HTTP 422 "Invalid parameters": início ou destino estão faltando,
profiletem um valor desconhecido oualternativesnão é0nem1. Emdetailsaparece o campo, por exemplo{"profile":["..."]}. O texto da mensagem está em alemão no momento. - HTTP 404 "No route found for the specified coordinates": não há rota entre os pontos, como de carro atravessando o mar, ou um ponto está longe demais de qualquer via. Um valor inválido em
avoidtambém leva a essa mensagem. - HTTP 500 com
{"message":"Server Error"}: verifique o formato das coordenadas. Cada ponto precisa de exatamente dois números, com ponto como separador decimal, separados por vírgula, e com valores válidos. No momento, o Maps responde a um formato errado com um erro de servidor em vez de uma mensagem clara. - A rota termina em um lugar totalmente errado: em geral, longitude e latitude estão invertidas. Veja O Maps não encontra nada ou mostra o lugar errado: o que fazer?.
Quanto custa uma rota?
As rotas são cobradas a cada 1.000 requisições bem-sucedidas e têm preço próprio, acima do da busca e da geocodificação. 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
- Se você repetir uma requisição com exatamente os mesmos pontos, opções e idioma, o Maps responde a partir de um cache. É mais rápido e é cobrado como qualquer resposta bem-sucedida, mas com
driving-traffictambém significa que o tempo de viagem reflete o trânsito do momento do primeiro cálculo. Para orçamentos e planejamento,drivingcostuma ser a melhor escolha. - A resposta traz um aviso de uso no campo
attribution. Os dados não podem ser armazenados de forma permanente.