Documentação da API e Playground

Chave de teste:b602a7df...

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

docs.sections.directions.responseDesc

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

docs.sections.snap.responseDesc

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).

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 (id, capacidade, endereço de partida, etc.).
services	array	Obrigatório	[]	Os endereços a serem atendidos (id, coordenadas, tempo de serviço, etc.).

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.