Documentação da API e Playground

Chave de teste:YOUR_API...

Introdução

A OSRMRoute Directions API é um serviço web RESTful criado para integrar roteamento geoespacial rápido e de alto desempenho, matrizes de viagem, busca de endereços (geocodificação) e otimização de rotas às suas aplicações. Esta documentação explica em detalhes todas as capacidades da API, os parâmetros e as etapas de integração.

Autenticação

As solicitações à API OSRMRoute usam uma chave de API única para autenticação. Você pode adicionar sua chave de API a cada solicitação como parâmetro de consulta (?key=YOUR_KEY) ou pelo cabeçalho HTTP Authorization (como token Bearer).

GETAny endpoint

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
key	string	Obrigatório	-	A chave de API única obtida do seu painel pessoal. Esta chave determina os limites das suas solicitações.

Códigos de erro

A OSRMRoute usa códigos de status HTTP padrão e mensagens de erro JSON detalhadas para indicar o estado de uma solicitação.

Explicação da estrutura da resposta

Principais códigos de status e seu significado: - **200 OK**: A solicitação foi concluída com sucesso. - **400 Bad Request**: Os parâmetros são inválidos ou estão ausentes. - **401 Unauthorized**: A chave de API não foi fornecida ou é inválida. - **403 Forbidden**: A chave de API está bloqueada ou inativa. - **429 Too Many Requests**: O limite diário de créditos foi excedido. - **500 Internal Error**: Ocorreu um erro interno do sistema.

Routing API

Calcula a rota mais rápida e mais curta do ponto A ao ponto B (com pontos via intermediários). Retorna instruções passo a passo (turn-by-turn) e geometria GeoJSON para diferentes perfis de transporte (driving, cycling, walking).

GET/api/v1/osrm/route/v1/{profile}/{coordinates}

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
profile	string	Obrigatório	driving	Perfil do modo de transporte. Valores suportados: driving (carro), cycling (bicicleta), walking (pedestre).
coordinates	string	Obrigatório	-	Coordenadas dos pontos. Formato: lon,lat;lon,lat;lon,lat... (no mínimo 2 pontos).
overview	string	Opcional	full	Nível de detalhe da geometria de rota retornada: simplified (simplificada), full (geometria completa), false (sem geometria).
geometries	string	Opcional	geojson	Formato da geometria: geojson (objeto GeoJSON), polyline (string codificada).
steps	boolean	Opcional	true	Se instruções passo a passo são retornadas para cada conversão.

Explicação da estrutura da resposta

Uma resposta bem-sucedida contém a distância total da rota (em metros), a duração da viagem (em segundos), os pontos de passagem e a linha da rota em GeoJSON.

Matrix API

Calcula uma matriz rápida de distância e tempo de viagem entre vários pontos (uma tabela NxM). Uma ferramenta ideal para otimizar rotas logísticas.

GET/api/v1/osrm/table/v1/{profile}/{coordinates}

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
profile	string	Obrigatório	driving	Perfil de transporte (driving, cycling, walking).
coordinates	string	Obrigatório	-	Pontos da matriz. Formato: lon,lat;lon,lat;lon,lat...
annotations	string	Opcional	duration,distance	Dados a calcular: duration (tempo), distance (distância) ou ambos.

Explicação da estrutura da resposta

Uma resposta bem-sucedida retorna uma tabela-matriz bidimensional de distances (distâncias) e durations (durações) para cada combinação de ponto de início e fim.

Map Matching API

Ajusta traços de GPS imprecisos à rede viária real (snap to road). Usado para limpar o ruído nos sinais de GPS.

GET/api/v1/osrm/match/v1/{profile}/{coordinates}

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
profile	string	Obrigatório	driving	Perfil de transporte.
coordinates	string	Obrigatório	-	A sequência de coordenadas de GPS a ajustar (lon,lat;lon,lat...)
overview	string	Opcional	full	Precisão da geometria da rota ajustada.

Nearest API

Ajusta qualquer coordenada ao segmento de via real mais próximo (snap) e retorna informações sobre o nome da via.

GET/api/v1/osrm/nearest/v1/{profile}/{coordinates}

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
profile	string	Obrigatório	driving	Perfil de transporte.
coordinates	string	Obrigatório	-	O ponto a pesquisar por perto. Formato: lon,lat (um único par).
number	integer	Opcional	3	O número de vias candidatas mais próximas a encontrar.

Trip API

Resolve o Problema do Caixeiro-Viajante (TSP): encontra a rota circular (ou aberta) mais ótima para visitar um conjunto de pontos dado e ordena os pontos.

GET/api/v1/osrm/trip/v1/{profile}/{coordinates}

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
profile	string	Obrigatório	driving	Perfil de transporte.
coordinates	string	Obrigatório	-	Pontos a visitar. Formato: lon,lat;lon,lat...
source	string	Opcional	any	O ponto de onde a rota pode começar (any ou o primeiro ponto).
destination	string	Opcional	any	O ponto onde a rota termina (any ou o último ponto).

Directions API

Retorna navegação passo a passo entre dois ou mais pontos com uma lista de instruções limpa (texto, distância, duração, tipo de manobra e localização). Suporta carro, bicicleta e a pé, além de até 3 rotas alternativas em uma única chamada.

GET/api/1/directions

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
point	string	Obrigatório	lat,lng	Ponto como lat,lng. Repita o parâmetro para cada parada (mínimo 2).
profile	string	Opcional	driving	Modo de transporte: driving, cycling ou walking.
alternatives	integer	Opcional	0	Número de rotas alternativas adicionais a retornar (0–3).
lang	string	Opcional	en	Código de idioma para o texto das instruções.

Explicação da estrutura da resposta

Retorna { code, profile, routes[], waypoints[] }. Cada rota tem distance (m), duration (s), uma geometria GeoJSON e um array instructions[]; cada instrução inclui text, type, modifier, distance, duration, name e location [lat,lng].

Snap to Road API

Ajusta pontos GPS brutos e imprecisos à posição mais próxima da malha viária. Repita o parâmetro point para cada coordenada (até 100).

GET/api/1/snap

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
point	string	Obrigatório	lat,lng	Ponto GPS como lat,lng. Repita o parâmetro para cada ponto (máximo 100).
profile	string	Opcional	driving	Rede viária para ajuste: driving, cycling ou walking.

Explicação da estrutura da resposta

Retorna { code, profile, snapped[] }. Cada item inclui o input original [lat,lng], a posição ajustada [lat,lng], a distância de ajuste em metros e o nome da via.

Geocoding API

Converte um texto de busca em coordenadas geográficas (direta) ou coordenadas em um endereço (reversa). Autocompletar rápido e tolerante a erros de digitação que cobre ruas, endereços e pontos de interesse (cafés, lojas, hotéis, escritórios). Ideal para busca conforme se digita.

GET/api/1/geocode

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
q	string	Obrigatório	-	O endereço a pesquisar (ex.: «Rua Nizami, Baku»).
reverse	boolean	Opcional	false	Deve ser true para realizar geocodificação reversa (busca de coordenada para endereço).
point	string	Opcional	lat,lng	Coordenada (lat,lng) para geocodificação reversa em endereço. Obrigatório quando reverse=true.
limit	integer	Opcional	5	Número máximo de resultados a retornar (1–20, padrão 5).
lang	string	Opcional	en	Idioma preferido para os nomes dos resultados (ex. en, az, ru). Padrão en.
lat	number	Opcional	-	Latitude para enviesar os resultados (próximos primeiro). Junto com lon.
lon	number	Opcional	-	Longitude para enviesar os resultados. Junto com lat.
bbox	string	Opcional	-	Restringir resultados a uma caixa: minLon,minLat,maxLon,maxLat.
osm_tag	string	Opcional	-	Filtrar por tag OSM, ex. place (localidades) ou amenity:cafe. Prefixo ! para excluir.
city	string	Opcional	-	Priorizar os resultados desta cidade no topo (ex. Bakı), sem ocultar os demais.
elastic	boolean	Opcional	true	Busca elástica (difusa, alta cobertura) — padrão true. Tolera erros de digitação, ausência de diacríticos (ə↔e), ordem das palavras, palavras genéricas (metro, rayonu) e números de casa. false para correspondência estrita.

Exemplos

# Enviesar para um local, apenas localidades
GET /api/1/geocode?q=qala&lat=40.41&lon=49.87&osm_tag=place&key=YOUR_KEY

# Priorizar uma cidade no topo
GET /api/1/geocode?q=market&city=Bakı&key=YOUR_KEY

# Geocodificação reversa (coordenadas para endereço)
GET /api/1/geocode?reverse=true&point=40.409,49.867&key=YOUR_KEY

Lugares (POI próximos)

Encontre pontos de interesse perto de um local — cafés, lojas, hotéis, caixas eletrônicos, farmácias e mais — filtrados por categoria e raio, ordenados por distância.

GET/api/1/places

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
point	string	Obrigatório	lat,lng	Coordenada central lat,lng (obrigatório).
radius	number	Opcional	1	Raio de busca em quilômetros (0.05–20, padrão 1).
category	string	Opcional	-	Filtro por tag OSM, ex. amenity:cafe, shop, tourism:hotel. Prefixo ! para excluir. Vazio = todos os POI.
limit	integer	Opcional	10	Máx. de resultados (1–50, padrão 10).
lang	string	Opcional	en	Idioma preferido para os nomes (ex. en, az, ru).

Autocomplete API

Sugestões de lugares rápidas e tolerantes a erros conforme o usuário digita, com viés por localização.

GET/api/1/autocomplete

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
q	string	Obrigatório	-	Texto de busca — entrada parcial é aceita.
limit	integer	Opcional	8	Número máximo de sugestões (1–15).
lang	string	Opcional	en	Código de idioma para os rótulos.
lat	number	Opcional	-	Latitude para direcionar resultados (opcional).
lon	number	Opcional	-	Longitude para direcionar resultados (opcional).
osm_tag	string	Opcional	-	Filtra as sugestões por tipo OSM, ex. place:city.

Explicação da estrutura da resposta

Retorna { suggestions[], took }. Cada sugestão tem label, name, city, state, country, countrycode, type, osm_id e point {lat,lng}.

Batch Geocoding API

Geocodifique centenas de endereços em uma única requisição — ideal para pipelines de dados e importações.

POST/api/1/geocode/batch

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
queries	array	Obrigatório	[]	Array de endereços a geocodificar (máx. 100).
lang	string	Opcional	en	Código de idioma para os rótulos.
limit	integer	Opcional	1	Máximo de correspondências por consulta (1–5).

Explicação da estrutura da resposta

Retorna { results[], count, took }. Cada resultado associa a consulta de entrada a um array hits[]; cada correspondência inclui label, city, country e point {lat,lng}. A ordem de entrada é mantida.

Timezone API

Fuso horário IANA, deslocamento UTC atual, status do horário de verão e hora local para qualquer coordenada.

GET/api/1/timezone

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
point	string	Obrigatório	lat,lng	Coordenada como lat,lng.
lat	number	Opcional	-	Latitude (alternativa a point).
lon	number	Opcional	-	Longitude (alternativa a point).
timestamp	integer	Opcional	now	Tempo Unix (segundos) ou data ISO para resolver o deslocamento; padrão agora.

Explicação da estrutura da resposta

Retorna { timezone, point, utc_offset, utc_offset_seconds, dst, abbreviation, local_time, utc_time }. utc_offset é uma string +HH:MM, dst é true quando o horário de verão está ativo, e local_time é um carimbo ISO com o deslocamento do fuso.

Elevation API

Altitude acima do nível do mar, em metros, para qualquer coordenada — um ponto ou o perfil de toda uma rota.

GET/api/1/elevation

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
point	string	Obrigatório	lat,lng	Coordenada como lat,lng. Repita para cada ponto (até 100 no GET).

Explicação da estrutura da resposta

Retorna { results[], unit:"meters" }, onde cada resultado é { point:{lat,lng}, elevation }. elevation é em metros acima do nível do mar (null se desconhecido, 0 sobre o mar). Para um único ponto, um campo elevation de nível superior também é incluído. Para lotes grandes, POST { points:[[lat,lng],...] } (até 1000).

Boundary Lookup API

Descubra em que país, estado, cidade e distrito uma coordenada cai — com o polígono do limite, se solicitado.

GET/api/1/boundary

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
point	string	Obrigatório	lat,lng	Coordenada como lat,lng.
polygon	boolean	Opcional	false	true para também retornar o limite como GeoJSON.
lang	string	Opcional	en	Código de idioma para os nomes.

Explicação da estrutura da resposta

Retorna { point, display_name, country, countrycode, state, county, city, district, postcode, osm_id, osm_type } e, com polygon=true, uma geometria de limite GeoJSON.

Geofencing API

Verifique em uma chamada em quais das suas zonas cada ponto cai — cercas poligonais ou circulares.

POST/api/1/geofence

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
fences	array	Obrigatório	[]	Array de cercas: { id?, polygon:[[lat,lng],...] } ou { id?, center:[lat,lng], radius_m }. Até 100.
points	array	Obrigatório	[]	Array de pontos [lat,lng] a testar (até 1000).

Explicação da estrutura da resposta

Retorna { results[], count }. Cada resultado é { point:{lat,lng}, inside:[fenceId,...] } listando todas as cercas em que o ponto cai (vazio se nenhuma).

Elevation Profile API

Altitude em cada ponto de um trajeto mais ganho, perda e distância totais — um perfil completo.

POST/api/1/elevation/profile

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
points	array	Obrigatório	[]	Array de pontos [lat,lng] do trajeto (>=2, até 2000).
polyline	string	Opcional	-	Polyline codificada como alternativa a points.

Explicação da estrutura da resposta

Retorna { profile[], total_ascent, total_descent, min_elevation, max_elevation, distance, unit }. Cada item { point, elevation, distance } (metros).

Solar API

Nascer, pôr do sol, crepúsculo, meio-dia solar e duração do dia para qualquer coordenada e data.

GET/api/1/solar

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
point	string	Obrigatório	lat,lng	Coordenada como lat,lng.
date	string	Opcional	today	Data (YYYY-MM-DD) a calcular; padrão hoje.

Explicação da estrutura da resposta

Retorna { point, date, sunrise, sunset, solar_noon, dawn, dusk, golden_hour, night_start, night_end, day_length_seconds }. Horas em UTC ISO; null em dia/noite polar.

Geometry Utilities API

Distância, rumo, área, centroide, simplificação e polyline encode/decode — matemática espacial como serviço.

POST/api/1/geometry

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
op	string	Obrigatório	distance	Operação: distance, bearing, destination, midpoint, length, area, centroid, simplify, polyline_encode ou polyline_decode.
from	array	Opcional	[lat,lng]	Ponto inicial [lat,lng].
to	array	Opcional	[lat,lng]	Ponto final [lat,lng].
path	array	Opcional	[]	Array de [lat,lng] (length/simplify/polyline_encode).
polygon	array	Opcional	[]	Anel [lat,lng] (area).

Explicação da estrutura da resposta

Retorna { op, ... } com o resultado da operação, ex. { distance, unit }, { bearing_deg }, { point }, { area, unit }, { path } ou { polyline }.

Coordinate Conversion API

Converte latitude/longitude de e para referências de grade UTM e MGRS.

GET/api/1/convert

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
point	string	Obrigatório	lat,lng	Coordenada lat,lng para converter em UTM/MGRS.
mgrs	string	Opcional	-	String MGRS para converter de volta em coordenada.

Explicação da estrutura da resposta

Retorna { point, mgrs, utm:{ zone, band, easting, northing, hemisphere } }. Com mgrs= retorna { mgrs, point }.

Country Info API

Moeda, código telefônico, idiomas, capital e bandeira de qualquer país por código ISO ou nome.

GET/api/1/country

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
code	string	Obrigatório	AZ	Código de país ISO 3166 alfa-2 ou alfa-3 (ex. AZ ou AZE).
name	string	Opcional	-	Nome do país como alternativa ao código.

Explicação da estrutura da resposta

Retorna { name, official_name, cca2, cca3, capital, region, subregion, currency:{code,name,symbol}, calling_code, languages[], flag, latlng, population }.

Isochrone API

Retorna polígonos das zonas geográficas alcançáveis a partir de um ponto dado dentro de um tempo ou distância determinados.

GET/api/1/isochrone

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
point	string	Obrigatório	-	Ponto central. Formato: lat,lon.
time_limit	integer	Opcional	600	Limite de tempo de viagem (em segundos).

Route Optimization API

Otimiza as rotas de uma frota de veículos (Vehicle Routing Problem). Calcula o plano de entrega e transporte dos veículos com o menor custo.

POST/api/1/vrp

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
vehicles	array	Obrigatório	[]	A lista de veículos — cada um com um id, capacidade opcional e um local de início como um array [lon, lat] (longitude primeiro).
services	array	Obrigatório	[]	As paradas a atender — cada uma com um id, um local como array [lon, lat] (longitude primeiro) e tempo de serviço opcional. Mesma ordem de coordenadas de todos os nossos endpoints.

Location Clustering API

Agrupa (em clusters) as coordenadas dadas de acordo com sua proximidade e densidade geográfica.

POST/api/1/cluster

Parâmetros (Query Params)

Parâmetro	Tipo	Status	Padrão	Descrição
customers	array	Obrigatório	[]	Coordenadas de clientes e pesos a serem agrupados em clusters.

SDK oficiais

Zero dependências, totalmente tipado, todos os endpoints. Faça a primeira chamada em menos de um minuto.

osrmrouteosrmrouteVer os SDK