osrmroute
Documentação de APIs, SDKs e guias de integraçãoIntegração e migração
OSRMRoute / API

Documentação de APIs, SDKs e guias de integração

Consulte endpoints, autenticação, limites e exemplos de API. Integre SDKs móveis, CLI, MCP, estilos de mapas, pesquisa de lugares e dados viários.

OpenAPI · Postman

Catálogo de APIs

Encontre APIs por nome, uso ou endpoint. Cada item leva aos parâmetros, exemplos e limites de uso.

Navegação (10)
  • Routing API →

    Calcule uma rota pelos pontos na ordem enviada, de carro, bicicleta ou a pé. Use steps=true para instruções e geometries=geojson para GeoJSON.

    GET /api/v1/osrm/route/v1/{profile}/{coordinates}
  • Isochrones API →

    Estima a acessibilidade com base nos tempos de viagem até pontos de amostra. Se cada direção tiver um ponto alcançável, quality.status é estimated; caso contrário, é insufficient_data e polygons fica vazio. Um resultado vazio não prova que não existam vias alcançáveis. O limite é aproximado; apenas limites de tempo são suportados.

    GET /api/1/isochrone
  • 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}
  • 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}
  • 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
  • Alternative Routes 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
  • 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
  • API de estimativa de combustível →

    Estime combustível e valor da viagem com distância, peso carregado, consumos vazio/carga total e preço por litro. Separada ou no Truck.

    POST /api/v1/fuel/estimate
  • Truck Routing API →

    Planeje rotas de caminhão dentro do país e entre países com ligação rodoviária. Envie as dimensões e o peso do veículo carregado em cada solicitação.

    POST /api/v1/truck/route
  • Search Along Route API →

    Compare paragens e tempo adicional de condução ao longo da rota.

    POST /api/v1/places/along-route
Operações e planejamento de carga (7)
  • Route Optimization API →

    Planeja rotas com restrições de capacidade, janelas de tempo, habilidades e coletas/entregas vinculadas. Uma heurística com tempo limitado reduz a viagem sem garantir um ótimo global. Tarefas não atribuídas permanecem em solution.unassigned; entradas inválidas são rejeitadas por completo.

    POST /api/1/vrp
  • Matrix API →

    Calcule tempos, distâncias ou ambos entre origens e destinos. Selecione índices da lista de coordenadas com sources e destinations.

    GET /api/v1/osrm/table/v1/{profile}/{coordinates}
  • Trip API (TSP) →

    Ordene as paradas de um único veículo pela rede viária. Para uma rota aberta, envie roundtrip=false&source=first&destination=last. A ordem pode ser subótima.

    GET /api/v1/osrm/trip/v1/{profile}/{coordinates}
  • Agrupamento de locais →

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

    POST /api/1/cluster
  • Planeamento de carga →

    Planeje cargas mistas para caminhões, carretas e contêineres. Confira o empilhamento, a ordem e o espaço em 3D ou integre a API ao seu sistema.

    POST /api/v1/load-plansGET /api/v1/load-plansGET /api/v1/load-plans/{id}
    Todos os endpoints (+38)
    DELETE /api/v1/load-plans/{id}POST /api/v1/load-plans/{id}/cancelGET /api/v1/load-plans/{id}/worksheetGET /api/v1/load-plans/{id}/csvGET /api/v1/load-plans/{id}/modelGET /api/v1/load-plans/pricesGET /api/v1/load-plans/import-previewPOST /api/v1/load-plans/import-previewPOST /api/v1/load-plans/comparePOST /api/v1/load-plans/fleetPOST /api/v1/load-plans/{id}/placement-previewPOST /api/v1/load-plans/{id}/placement-revisionsGET /api/v1/load-plans/{id}/pdfGET /api/v1/load-plans/{id}/xlsxPOST /api/v1/load-plans/{id}/shareDELETE /api/v1/load-plans/{id}/sharePOST /api/v1/load-plans/shared-viewPOST /api/v1/load-plans/palletizePOST /api/v1/load-plans/{id}/axle-estimateGET /api/v1/load-plans/workspace/{kind}GET /api/v1/load-plans/workspace/{kind}/{id}PUT /api/v1/load-plans/workspace/{kind}/{id}DELETE /api/v1/load-plans/workspace/{kind}/{id}GET /api/v1/load-plans/webhookPOST /api/v1/load-plans/webhookDELETE /api/v1/load-plans/webhookGET /api/v1/load-plans/webhook/eventsPOST /api/v1/load-plans/webhook/events/{id}POST /api/v1/load-plans/multi-stopPOST /api/v1/load-plans/bulkPOST /api/v1/load-plans/packagingPOST /api/v1/load-plans/dispatchPOST /api/v1/load-plans/fulfillmentPOST /api/v1/load-plans/simulationGET /api/v1/load-plans/{id}/warehousePOST /api/v1/load-plans/{id}/warehouseGET /api/v1/load-plans/{id}/simulation-reportGET /api/v1/load-plans/partner
  • Análise de viagem: prova de visita →

    Evidência de visita e permanência a partir do trajeto enviado.

    POST /api/v1/trip-analytics/visit-proof
  • Otimização de frota de camiões →

    Matrizes estáticas de camião específicas por veículo.

    POST /api/v1/truck/optimize
Pesquisa (8)
  • 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
  • Places API →

    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
  • 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
  • Batch Geocoding API →

    Geocodifique até 100 endereços por requisição. Os resultados seguem a ordem de entrada, e cada endereço custa um crédito.

    POST /api/1/geocode/batch
  • Pesquisa em linguagem natural →

    Encontre locais com consultas curtas em inglês.

    POST /api/v1/search/natural
  • Detalhes dos locais →

    Consulte atributos fornecidos pela fonte.

    POST /api/v1/places/details
  • Structured Geocoding API →

    Pesquise endereços por rua, cidade, código postal e país.

    POST /api/v1/search/structured
  • Suggest & Retrieve API →

    Crie pesquisa de locais com sugestões e recuperação segura.

    POST /api/v1/search/suggestPOST /api/v1/search/retrieve
Mapas (4)
  • Prévia de estilo por texto →

    Descreva cores e camadas e reveja o mapa.

    POST /api/v1/studio/preview
  • Static Maps API →

    Exporte mapas estilizados em PNG para relatórios e aplicações.

    POST /api/v1/maps/static
  • Studio API →

    Gira estilos, conjuntos de dados e publicação na sua aplicação.

    GET /api/v1/studio/{resource}POST /api/v1/studio/{resource}
  • Estilos de mapa e blocos vetoriais →

    Carregue mapas-base públicos ou estilos publicados no MapLibre. Solicitações públicas dispensam chave e não consomem créditos. Use as URLs de blocos do estilo e mantenha a atribuição.

    GET /api/basemaps/{style}GET /api/map-styles/{id}GET /api/map-styles/{id}/tiles/{dataset}/{z}/{x}/{y}
    Todos os endpoints (+2)
    GET /api/private-maps/{id}GET /api/private-maps/{id}/tiles/{dataset}/{z}/{x}/{y}
Dados (15)
  • 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
  • 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
  • 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
  • Geofencing API →

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

    POST /api/1/geofence
  • 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
  • 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
  • Geometry Utilities API →

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

    POST /api/1/geometry
  • Coordinate Conversion API →

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

    GET /api/1/convert
  • 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
  • Dataset Query API →

    Encontre elementos próximos nos seus próprios dados geográficos.

    POST /api/v1/maps/datasets/{id}/query
  • API de dados rodoviários →

    Limites de velocidade, atributos das vias e observações de sinais na cobertura disponível.

    POST /api/v1/roads/lookupPOST /api/v1/roads/batch
  • Utilização da conta →

    Dados rodoviários: 100.000 operações por mês

    POST /api/v1/roads/usage
  • API de sinais de trânsito →

    Encontre observações de sinais numa área do mapa. Obtenha classificações, coordenadas, direções e datas de observação com paginação por cursor.

    POST /api/v1/roads/signs
  • Evidência de conformidade de rota →

    Evidência de velocidade qualificada por fonte para posições submetidas.

    POST /api/v1/roads/compliance
  • Consulta de limite de velocidade →

    Consulte o limite de velocidade mapeado para carros perto de uma coordenada. Se estiver ausente ou for ambíguo, o resultado é null.

    GET /api/1/speed-limit
Guia de integração da plataforma (6)
  • Tarefas assíncronas →

    Operações: geocode_batch, matrix, optimize. POST /api/jobs retorna 202 e um ID de tarefa. O mesmo Idempotency-Key e conteúdo retornam a tarefa existente; conteúdo diferente retorna 409.

    POST /api/jobsGET /api/jobsGET /api/jobs/{id}
    Todos os endpoints (+1)
    DELETE /api/jobs/{id}
  • API Sandbox →

    Valide a leitura das respostas no sandbox com dados de teste antes de uma chamada real paga.

    POST /api/sandbox
  • Metadados de fontes →

    Consulte as fontes, a cobertura geográfica e a atualização dos dados por serviço.

    GET /api/source-metadata
  • Acesso móvel →

    Ligue a aplicação sem incluir uma chave API secreta.

    POST /api/mobile/challengePOST /api/mobile/token
  • API MCP remota →

    Conecte ferramentas de IA aos serviços de localização.

    POST /api/mcp
  • Endpoints de compatibilidade →

    Antes de migrar uma integração, confira a ordem das coordenadas e as unidades da resposta.

    GET /api/v1/route/{profile}/{coordinates}GET /api/1/routeGET /api/1/route/info
    Todos os endpoints (+9)
    GET /api/1/matrixPOST /api/1/matrixPOST /api/1/matrix/calculatePOST /api/1/matchPOST /api/1/elevationPOST /api/1/optimizePOST /api/1/vrp/optimizePOST /api/1/cluster/calculatePOST /api/1/batch-geocode

Introdução

#

OSRMRoute oferece APIs de rotas, planejamento de frotas, busca de endereços, mapas e dados geográficos. Use o catálogo para encontrar o guia da operação a integrar.

Limites atuais dos planos

Os limites de créditos e pedidos por minuto são partilhados por todas as chaves da conta. Um limite adicional por chave não aumenta o orçamento. Os créditos incluídos são usados antes dos comprados.

Free inclui as APIs Routing, Route Optimization, Geocoding (com pesquisa inversa e preenchimento automático) e Matrix dentro dos limites do plano. Map Matching, Isochrone, Truck Routing, Fuel Estimate e outras APIs separadas exigem um plano pago, incluindo PAYG. O acesso às APIs segue o plano efetivo da conta; um saldo positivo, por si só, não elimina as restrições Free. Os dados rodoviários e AI mantêm os seus requisitos Business separados.

Route, Directions e Truck Routing: um pedido processado sem via acessível próxima ou sem rota ligada custa uma única vez 0,5 créditos em todos os planos elegíveis, incluindo PAYG. Dados inválidos, recusas de acesso/plano ou cobertura do grafo e erros do servidor não são cobrados. Primeiro reserva-se o preço de um pedido bem-sucedido; o restante é devolvido.

A carregar limites…

A demonstração pública suporta Route, Matrix, Match, Nearest e Trip com limites próprios. Para os restantes serviços, use a sua chave API e os exemplos abaixo.

Autenticação

#

Envie a chave como token Bearer no cabeçalho Authorization. Consulte o guia para verificar o escopo da chave e o ambiente exigidos. Alguns endpoints antigos aceitam chaves em parâmetros de URL.

HTTP
Authorization: Bearer YOUR_API_KEY

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.

Os erros incluem error e, por vezes, code. Verifique o estado HTTP e os cabeçalhos de saldo, não apenas a mensagem. Reset indica janelas móveis, não uma reposição à meia-noite.

X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset · X-Compute-* · X-Quota-* · X-Credits-* · Retry-After

Forneça uma chave API válida e verifique o estado.

HTTP 401
{
  "error": "Invalid API Key"
}

Recarregue o saldo ou escolha um plano adequado.

HTTP 402
{
  "error": "Insufficient balance: this request costs 1 credit and your balance is 0 credits. Top up your account to continue."
}

Verifique os limites de complexidade e as restrições da chave.

HTTP 403
{
  "error": "This API Key is disabled"
}

Respeite Retry-After e reduza a frequência dos pedidos.

HTTP 429
{
  "error": "Rate limit exceeded: this account has exceeded its configured requests-per-minute limit. Please slow down."
}

O serviço ou a fonte estão indisponíveis. Repita com cuidado e pausas crescentes.

HTTP 500
{
  "error": "Internal Server Error"
}

Routing API

#

Calcule uma rota pelos pontos na ordem enviada, de carro, bicicleta ou a pé. Use steps=true para instruções e geometries=geojson para GeoJSON.

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

Parâmetros (Query Params)

ParâmetroTipoStatusPadrãoDescrição
profilestringObrigatóriodrivingPerfil do modo de transporte. Valores suportados: driving (carro), cycling (bicicleta), walking (pedestre).
coordinatesstringObrigatório-Coordenadas dos pontos. Formato: lon,lat;lon,lat;lon,lat... (no mínimo 2 pontos).
overviewstringOpcionalsimplifiedNível de detalhe da geometria de rota retornada: simplified (simplificada), full (geometria completa), false (sem geometria).
geometriesstringOpcionalpolylineFormato da geometria: geojson (objeto GeoJSON), polyline (string codificada).
stepsbooleanOpcionalfalseSe instruções passo a passo são retornadas para cada conversão.
alternativesinteger | booleanOpcionalfalseQuantidade de alternativas a buscar. A disponibilidade depende da rede viária.

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Routing API
curl "https://osrmroute.com/api/v1/osrm/route/v1/driving/49.8516,40.3777;49.86,40.40?steps=true&overview=full&geometries=geojson" -H "Authorization: Bearer YOUR_KEY"

Limites e coordenadas

Custo em créditos: 1 crédito por cada bloco iniciado de 10 pontos de entrada, incluindo origem e destino.

Route, Directions e Truck Routing: um pedido processado sem via acessível próxima ou sem rota ligada custa uma única vez 0,5 créditos em todos os planos elegíveis, incluindo PAYG. Dados inválidos, recusas de acesso/plano ou cobertura do grafo e erros do servidor não são cobrados. Primeiro reserva-se o preço de um pedido bem-sucedido; o restante é devolvido.

Caminho OSRM: lon,lat; GeoJSON: [lon,lat].

  • points ≥ 2; points ≤ plan.maxRoutePoints
  • snap_distance_m ≤ 2000

Os perfis de carro, caminhada e ciclismo são globais. Os pontos devem conectar-se por vias permitidas.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "code": "Ok",
  "routes": [
    {
      "distance": 3200,
      "duration": 420,
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [
            49.8516,
            40.3777
          ],
          [
            49.86,
            40.4
          ]
        ]
      },
      "legs": [
        {
          "distance": 3200,
          "duration": 420,
          "steps": []
        }
      ]
    }
  ],
  "waypoints": [
    {
      "name": "Example road",
      "location": [
        49.8516,
        40.3777
      ],
      "distance": 4.2
    }
  ]
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "code": "InvalidQuery",
  "error": "Coordinates must be finite longitude,latitude pairs."
}

Escolha um perfil suportado. Não há mudança automática para carro.

HTTP 422
{
  "code": "ProfileNotAvailable",
  "error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}

A API não conseguiu atender todos os pontos em uma mesma rede viária para o perfil escolhido. Envie os trechos conectados separadamente.

HTTP 422
{
  "code": "CrossRegionNotSupported",
  "error": "These coordinates are not served by one routing graph. Split the request by region."
}

Confira se os pontos estão perto de vias acessíveis e se as vias são conectadas para o perfil escolhido.

HTTP 422
{
  "code": "NoNearbyRoad",
  "error": "No connected route within 2000 metres of the requested coordinates."
}

O serviço ou a fonte estão indisponíveis. Repita com cuidado e pausas crescentes.

HTTP 504
{
  "code": "RoutingTimeout",
  "error": "The routing service did not respond within the request deadline. Retry later."
}

Explicação da estrutura da resposta

A distância é dada em metros e a duração em segundos. Por padrão, a linha é simplificada e codificada em polyline. Use overview=full para obter a linha completa.

Matrix API

#

Calcule tempos, distâncias ou ambos entre origens e destinos. Selecione índices da lista de coordenadas com sources e destinations.

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

Parâmetros (Query Params)

ParâmetroTipoStatusPadrãoDescrição
profilestringObrigatóriodrivingPerfil de transporte (driving, cycling, walking).
coordinatesstringObrigatório-Pontos da matriz. Formato: lon,lat;lon,lat;lon,lat...
annotationsstringOpcionaldurationDados a calcular: duration (tempo), distance (distância) ou ambos.
sourcesstringOpcionalallÍndices de origem a partir de zero, separados por ponto e vírgula, ou all.
destinationsstringOpcionalallÍndices de destino a partir de zero, separados por ponto e vírgula, ou all.

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Matrix API
curl "https://osrmroute.com/api/v1/osrm/table/v1/driving/49.85,40.37;49.86,40.40;49.83,40.39?annotations=duration,distance" -H "Authorization: Bearer YOUR_KEY"

Limites e coordenadas

Custo em créditos: max(1, ceil(cells * 2 / 5))

Caminho OSRM: lon,lat; GeoJSON: [lon,lat].

  • points ≥ 2; points ≤ plan.maxRoutePoints
  • cells = sources × destinations
  • credits = max(1, ceil(cells * 2 / 5))

Os perfis de carro, caminhada e ciclismo são globais. Os pontos devem conectar-se por vias permitidas.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "code": "Ok",
  "durations": [
    [
      0,
      420
    ],
    [
      430,
      0
    ]
  ],
  "distances": [
    [
      0,
      3200
    ],
    [
      3300,
      0
    ]
  ],
  "sources": [
    {
      "name": "Example road",
      "location": [
        49.8516,
        40.3777
      ],
      "distance": 4.2
    },
    {
      "name": "Second road",
      "location": [
        49.86,
        40.4
      ],
      "distance": 3
    }
  ],
  "destinations": [
    {
      "name": "Example road",
      "location": [
        49.8516,
        40.3777
      ],
      "distance": 4.2
    },
    {
      "name": "Second road",
      "location": [
        49.86,
        40.4
      ],
      "distance": 3
    }
  ]
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "code": "InvalidQuery",
  "error": "Coordinates must be finite longitude,latitude pairs."
}

Escolha um perfil suportado. Não há mudança automática para carro.

HTTP 422
{
  "code": "ProfileNotAvailable",
  "error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}

A API não conseguiu atender todos os pontos em uma mesma rede viária para o perfil escolhido. Envie os trechos conectados separadamente.

HTTP 422
{
  "code": "CrossRegionNotSupported",
  "error": "These coordinates are not served by one routing graph. Split the request by region."
}

Confira se os pontos estão perto de vias acessíveis e se as vias são conectadas para o perfil escolhido.

HTTP 422
{
  "code": "UnreachablePoints",
  "error": "Some locations are disconnected in this road network."
}

O serviço ou a fonte estão indisponíveis. Repita com cuidado e pausas crescentes.

HTTP 504
{
  "code": "RoutingTimeout",
  "error": "The routing service did not respond within the request deadline. Retry later."
}

Explicação da estrutura da resposta

A matriz durations é retornada por padrão. Use annotations=distance para distâncias ou annotations=duration,distance para ambas. Durações estão em segundos e distâncias em metros. Se nenhum grafo elegível puder completar a matriz, os pontos desconectados retornam HTTP 422 UnreachablePoints.

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âmetroTipoStatusPadrãoDescrição
geometriesstringOpcionalpolylineFormato da geometria: geojson (objeto GeoJSON), polyline (string codificada).
profilestringObrigatóriodrivingPerfil de transporte.
coordinatesstringObrigatório-A sequência de coordenadas de GPS a ajustar (lon,lat;lon,lat...)
overviewstringOpcionalsimplifiedPrecisão da geometria da rota ajustada.
timestampsstringOpcional-Horários Unix em segundos, em ordem não decrescente, um por ponto, separados por ponto e vírgula.
radiusesstringOpcional-Precisão do GPS em metros, um valor por ponto, separado por ponto e vírgula.

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Map Matching API
curl "https://osrmroute.com/api/v1/osrm/match/v1/driving/49.851536,40.375480;49.844011,40.379982;49.839336,40.389620;49.837774,40.389268?overview=full&geometries=geojson" -H "Authorization: Bearer YOUR_KEY"

Limites e coordenadas

Custo em créditos: 1 credit

Caminho OSRM: lon,lat; GeoJSON: [lon,lat].

  • points ≥ 2; points ≤ plan.maxRoutePoints
  • tracepoints[]: object | null

Os perfis de carro, caminhada e ciclismo são globais. Os pontos devem conectar-se por vias permitidas.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "code": "Ok",
  "matchings": [
    {
      "distance": 3200,
      "duration": 420,
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [
            49.8516,
            40.3777
          ],
          [
            49.86,
            40.4
          ]
        ]
      },
      "legs": [
        {
          "distance": 3200,
          "duration": 420,
          "steps": []
        }
      ],
      "confidence": 0.97
    }
  ],
  "tracepoints": [
    {
      "name": "Example road",
      "location": [
        49.8516,
        40.3777
      ],
      "distance": 4.2
    },
    null
  ]
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "code": "InvalidQuery",
  "error": "Coordinates must be finite longitude,latitude pairs."
}

Escolha um perfil suportado. Não há mudança automática para carro.

HTTP 422
{
  "code": "ProfileNotAvailable",
  "error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}

A API não conseguiu atender todos os pontos em uma mesma rede viária para o perfil escolhido. Envie os trechos conectados separadamente.

HTTP 422
{
  "code": "CrossRegionNotSupported",
  "error": "These coordinates are not served by one routing graph. Split the request by region."
}

Confira se os pontos estão perto de vias acessíveis e se as vias são conectadas para o perfil escolhido.

HTTP 422
{
  "code": "NoNearbyRoad",
  "error": "No connected route within 2000 metres of the requested coordinates."
}

O serviço ou a fonte estão indisponíveis. Repita com cuidado e pausas crescentes.

HTTP 504
{
  "code": "RoutingTimeout",
  "error": "The routing service did not respond within the request deadline. Retry later."
}

Explicação da estrutura da resposta

matchings[]: distance — distância (m), duration — duração (s), confidence — confiança (0–1), geometry — geometria; tracepoints[] — objeto ou null.

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âmetroTipoStatusPadrãoDescrição
profilestringObrigatóriodrivingPerfil de transporte.
coordinatesstringObrigatório-O ponto a pesquisar por perto. Formato: lon,lat (um único par).
numberintegerOpcional1O número de vias candidatas mais próximas a encontrar.

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Nearest API
curl "https://osrmroute.com/api/v1/osrm/nearest/v1/driving/49.8516,40.3777?number=3" -H "Authorization: Bearer YOUR_KEY"

Limites e coordenadas

Custo em créditos: 1 credit

Caminho OSRM: lon,lat; GeoJSON: [lon,lat].

  • coordinates: 1
  • number: default = 1; example = 3

Os perfis de carro, caminhada e ciclismo são globais. Os pontos devem conectar-se por vias permitidas.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "code": "Ok",
  "waypoints": [
    {
      "name": "Example road",
      "location": [
        49.8516,
        40.3777
      ],
      "distance": 4.2
    }
  ]
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "code": "InvalidQuery",
  "error": "Coordinates must be finite longitude,latitude pairs."
}

Escolha um perfil suportado. Não há mudança automática para carro.

HTTP 422
{
  "code": "ProfileNotAvailable",
  "error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}

Confira se os pontos estão perto de vias acessíveis e se as vias são conectadas para o perfil escolhido.

HTTP 422
{
  "code": "NoNearbyRoad",
  "error": "No connected route within 2000 metres of the requested coordinates."
}

O serviço ou a fonte estão indisponíveis. Repita com cuidado e pausas crescentes.

HTTP 504
{
  "code": "RoutingTimeout",
  "error": "The routing service did not respond within the request deadline. Retry later."
}

Explicação da estrutura da resposta

waypoints[] → name, distance (m), location [lon,lat].

Trip API

#

Ordene as paradas de um único veículo pela rede viária. Para uma rota aberta, envie roundtrip=false&source=first&destination=last. A ordem pode ser subótima.

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

Parâmetros (Query Params)

ParâmetroTipoStatusPadrãoDescrição
geometriesstringOpcionalpolylineFormato da geometria: geojson (objeto GeoJSON), polyline (string codificada).
profilestringObrigatóriodrivingPerfil de transporte.
coordinatesstringObrigatório-Pontos a visitar. Formato: lon,lat;lon,lat...
sourcestringOpcionalanyO ponto de onde a rota pode começar (any ou o primeiro ponto).
destinationstringOpcionalanyO ponto onde a rota termina (any ou o último ponto).
roundtripbooleanOpcionaltrueRetornar ao início. Para false, use source=first e destination=last.

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Trip API (TSP)
curl "https://osrmroute.com/api/v1/osrm/trip/v1/driving/49.85,40.37;49.86,40.40;49.83,40.39?source=first&geometries=geojson" -H "Authorization: Bearer YOUR_KEY"

Limites e coordenadas

Custo em créditos: 5 credits

Caminho OSRM: lon,lat; GeoJSON: [lon,lat].

  • points ≥ 2; points ≤ plan.maxRoutePoints
  • credits = 5

Os perfis de carro, caminhada e ciclismo são globais. Os pontos devem conectar-se por vias permitidas.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "code": "Ok",
  "trips": [
    {
      "distance": 3200,
      "duration": 420,
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [
            49.8516,
            40.3777
          ],
          [
            49.86,
            40.4
          ]
        ]
      },
      "legs": [
        {
          "distance": 3200,
          "duration": 420,
          "steps": []
        }
      ]
    }
  ],
  "waypoints": [
    {
      "name": "Example road",
      "location": [
        49.8516,
        40.3777
      ],
      "distance": 4.2,
      "trips_index": 0,
      "waypoint_index": 0
    }
  ]
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "code": "InvalidQuery",
  "error": "Coordinates must be finite longitude,latitude pairs."
}

Escolha um perfil suportado. Não há mudança automática para carro.

HTTP 422
{
  "code": "ProfileNotAvailable",
  "error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}

A API não conseguiu atender todos os pontos em uma mesma rede viária para o perfil escolhido. Envie os trechos conectados separadamente.

HTTP 422
{
  "code": "CrossRegionNotSupported",
  "error": "These coordinates are not served by one routing graph. Split the request by region."
}

Confira se os pontos estão perto de vias acessíveis e se as vias são conectadas para o perfil escolhido.

HTTP 422
{
  "code": "NoNearbyRoad",
  "error": "No connected route within 2000 metres of the requested coordinates."
}

O serviço ou a fonte estão indisponíveis. Repita com cuidado e pausas crescentes.

HTTP 504
{
  "code": "RoutingTimeout",
  "error": "The routing service did not respond within the request deadline. Retry later."
}

Explicação da estrutura da resposta

trips[]: distance — distância (m), duration — duração (s), geometry — geometria; waypoints[]: trips_index, waypoint_index — índices de ordem, location [lon,lat] — coordenadas.

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âmetroTipoStatusPadrãoDescrição
pointstringObrigatóriolat,lngPonto como lat,lng. Repita o parâmetro para cada parada (mínimo 2).
profilestringOpcionaldrivingModo de transporte: driving, cycling ou walking.
alternativesintegerOpcional0Número de rotas alternativas adicionais a retornar (0–3).
langstringOpcionalenCódigo de idioma para o texto das instruções.

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Directions API
curl "https://osrmroute.com/api/1/directions?point=40.3777,49.8516&point=40.40,49.86&profile=driving" -H "Authorization: Bearer YOUR_KEY"
Alternative Routes API
curl "https://osrmroute.com/api/1/directions?point=40.3777,49.8516&point=40.40,49.86&alternatives=2" -H "Authorization: Bearer YOUR_KEY"

Limites e coordenadas

Custo em créditos: 1 crédito por cada bloco iniciado de 10 pontos de entrada, incluindo origem e destino.

Route, Directions e Truck Routing: um pedido processado sem via acessível próxima ou sem rota ligada custa uma única vez 0,5 créditos em todos os planos elegíveis, incluindo PAYG. Dados inválidos, recusas de acesso/plano ou cobertura do grafo e erros do servidor não são cobrados. Primeiro reserva-se o preço de um pedido bem-sucedido; o restante é devolvido.

Entrada point=lat,lng. Instruções e paragens: [lat,lng]; GeoJSON: [lon,lat].

  • point: repeat ≥ 2; count ≤ plan.maxRoutePoints
  • alternatives: 0–3

Os perfis de carro, caminhada e ciclismo são globais. Os pontos devem conectar-se por vias permitidas.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "code": "Ok",
  "profile": "driving",
  "routes": [
    {
      "distance": 3200,
      "duration": 420,
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [
            49.8516,
            40.3777
          ],
          [
            49.86,
            40.4
          ]
        ]
      },
      "instructions": [
        {
          "text": "Continue on Example road",
          "type": "continue",
          "modifier": "straight",
          "distance": 300,
          "duration": 40,
          "name": "Example road",
          "bearing_after": 90,
          "location": [
            40.3777,
            49.8516
          ]
        }
      ]
    }
  ],
  "waypoints": [
    {
      "name": "Example road",
      "location": [
        40.3777,
        49.8516
      ]
    }
  ]
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "error": "At least two points must be provided (point=lat,lng repeated)."
}

Escolha um perfil suportado. Não há mudança automática para carro.

HTTP 422
{
  "code": "ProfileNotAvailable",
  "error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}

A API não conseguiu atender todos os pontos em uma mesma rede viária para o perfil escolhido. Envie os trechos conectados separadamente.

HTTP 422
{
  "code": "CrossRegionNotSupported",
  "error": "These coordinates are not served by one routing graph. Split the request by region."
}

Confira se os pontos estão perto de vias acessíveis e se as vias são conectadas para o perfil escolhido.

HTTP 422
{
  "code": "NoNearbyRoad",
  "error": "No connected route within 2000 metres of the requested coordinates."
}

O serviço ou a fonte estão indisponíveis. Repita com cuidado e pausas crescentes.

HTTP 504
{
  "code": "RoutingTimeout",
  "error": "The routing service did not respond within the request deadline. Retry later."
}

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âmetroTipoStatusPadrãoDescrição
pointstringObrigatóriolat,lngPonto GPS como lat,lng. Repita o parâmetro para cada ponto (máximo 100).
profilestringOpcionaldrivingRede viária para ajuste: driving, cycling ou walking.

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Snap to Road API
curl "https://osrmroute.com/api/1/snap?point=40.3778,49.8517&point=40.3801,49.8600" -H "Authorization: Bearer YOUR_KEY"

Limites e coordenadas

Custo em créditos: 1 credit

point=lat,lng; pontos JSON: [lat,lng]. Geometria GeoJSON: [lon,lat].

  • point: repeat 1–100

Os perfis de carro, caminhada e ciclismo são globais. Os pontos devem conectar-se por vias permitidas.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "code": "Ok",
  "profile": "driving",
  "snapped": [
    {
      "input": [
        40.3777,
        49.8516
      ],
      "snapped": [
        40.3778,
        49.8517
      ],
      "distance": 14,
      "name": "Example road"
    }
  ]
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "error": "At least one point must be provided (point=lat,lng repeated)."
}

Escolha um perfil suportado. Não há mudança automática para carro.

HTTP 422
{
  "code": "ProfileNotAvailable",
  "error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}

Confira se os pontos estão perto de vias acessíveis e se as vias são conectadas para o perfil escolhido.

HTTP 422
{
  "code": "NoNearbyRoad",
  "error": "No connected route within 2000 metres of the requested coordinates."
}

O serviço ou a fonte estão indisponíveis. Repita com cuidado e pausas crescentes.

HTTP 504
{
  "code": "RoutingTimeout",
  "error": "The routing service did not respond within the request deadline. Retry later."
}

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âmetroTipoStatusPadrãoDescrição
qstringOpcional-O endereço a pesquisar (ex.: «Rua Nizami, Baku»).
reversebooleanOpcionalfalseDeve ser true para realizar geocodificação reversa (busca de coordenada para endereço).
pointstringOpcionallat,lngCoordenada (lat,lng) para geocodificação reversa em endereço. Obrigatório quando reverse=true.
limitintegerOpcional5Número máximo de resultados a retornar (1–20, padrão 5).
langstringOpcionalenIdioma preferido para os nomes dos resultados (ex. en, az, ru). Padrão en.
latnumberOpcional-Latitude para enviesar os resultados (próximos primeiro). Junto com lon.
lonnumberOpcional-Longitude para enviesar os resultados. Junto com lat.
bboxstringOpcional-Restringir resultados a uma caixa: minLon,minLat,maxLon,maxLat.
osm_tagstringOpcional-Filtrar por tag OSM, ex. place (localidades) ou amenity:cafe. Prefixo ! para excluir.
countrystringOpcional-Código de país ISO 3166-1 alpha-2, por exemplo AZ. Somente resultados desse país.
citystringOpcional-Filtro estrito de cidade, por exemplo Baku. Exige exatamente um código country.
elasticbooleanOpcionaltrueBusca 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.

Filtros de país e cidade

Sem country, a busca é global. country=AZ limita os resultados ao Azerbaijão; country=AZ&city=Bakı a Baku no Azerbaijão. Sem correspondências, retorna HTTP 200 com uma lista vazia, sem ampliar a região. Cidade sem país ou código de país inválido retorna HTTP 400 InvalidGeocodeFilter. lat/lon afetam apenas a ordenação por proximidade. Registros sem cidade confirmada são excluídos quando há filtro de cidade.

Exemplos
GET /api/1/geocode?q=Nizami&country=AZ
GET /api/1/geocode?q=Nizami&country=AZ&city=Bak%C4%B1

HTTP 200: { "hits": [], "took": 12 }
HTTP 400: { "code": "InvalidGeocodeFilter", "error": "city requires exactly one country, for example country=AZ&city=Bakı." }

Exemplos

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

# Somente o país e a cidade selecionados
GET /api/1/geocode?q=market&country=AZ&city=Bak%C4%B1

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

Para pesquisar um endereço exato, informe a rua e o número em q. locality e postcode exigem um único país. unit seleciona uma unidade exata da fonte e ativa address_mode=units. O modo buildings padrão agrupa registros de unidades que compartilham a mesma localização.

GET
/api/1/geocode?q=101+Main+Street&country=US&locality=Boston&postcode=02129&unit=2&address_mode=units

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Geocoding API
curl "https://osrmroute.com/api/1/geocode?q=Nizami&country=AZ&city=Bak%C4%B1&lang=az" -H "Authorization: Bearer YOUR_KEY"

Limites e coordenadas

Custo em créditos: 1 credit

point=lat,lng; pontos JSON: [lat,lng]. Geometria GeoJSON: [lon,lat].

  • limit: 1–20
  • reverse: max_distance_m = 1000
  • city: exactly 1 country

Sem correspondências, uma resposta bem-sucedida pode conter uma lista vazia. Os filtros de país/cidade não são alargados. O detalhe dos endereços depende do índice.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "hits": [
    {
      "name": "Nizami Street",
      "city": "Baku",
      "country": "Azerbaijan",
      "countrycode": "AZ",
      "point": {
        "lat": 40.3777,
        "lng": 49.8516
      }
    }
  ],
  "took": 12
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "error": "The \"q\" parameter (search text) is required."
}

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "code": "InvalidGeocodeFilter",
  "error": "city requires exactly one country, for example country=AZ&city=Bakı."
}

Não existe endereço ou lugar indexado no raio de pesquisa inversa.

HTTP 422
{
  "code": "NoNearbyAddress",
  "error": "No indexed address or place within 1 km."
}

Explicação da estrutura da resposta

hits[]: name, city, country, countrycode — local e país, point (lat,lng) — coordenadas; took — tempo (ms). reverse=true: source — origem, accuracy — precisão, distance_m — distância.

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âmetroTipoStatusPadrãoDescrição
pointstringObrigatóriolat,lngCoordenada central lat,lng (obrigatório).
radiusnumberOpcional1Raio de busca em quilômetros (0.05–20, padrão 1).
categorystringOpcional-Filtro por tag OSM, ex. amenity:cafe, shop, tourism:hotel. Prefixo ! para excluir. Vazio = todos os POI.
limitintegerOpcional10Máx. de resultados (1–50, padrão 10).
langstringOpcionalenIdioma preferido para os nomes (ex. en, az, ru).

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Places API
curl "https://osrmroute.com/api/1/places?point=40.371,49.845&radius=1&category=amenity:cafe" -H "Authorization: Bearer YOUR_KEY"

Limites e coordenadas

Custo em créditos: 1 credit

point=lat,lng; pontos JSON: [lat,lng]. Geometria GeoJSON: [lon,lat].

  • radius: 0.05–20 km
  • limit: 1–50

Sem correspondências, uma resposta bem-sucedida pode conter uma lista vazia. Os filtros de país/cidade não são alargados. O detalhe dos endereços depende do índice.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "places": [
    {
      "name": "Example cafe",
      "category": "amenity",
      "type": "cafe",
      "distance_m": 85,
      "point": {
        "lat": 40.3777,
        "lng": 49.8516
      }
    }
  ],
  "took": 12
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "error": "The \"point\" parameter (lat,lng) is required."
}

O serviço ou a fonte estão indisponíveis. Repita com cuidado e pausas crescentes.

HTTP 502
{
  "error": "Places service unavailable."
}

Explicação da estrutura da resposta

places[]: name, category, type — dados do local, distance_m — distância, point (lat,lng) — coordenadas; took — tempo (ms).

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âmetroTipoStatusPadrãoDescrição
qstringObrigatório-Texto de busca — entrada parcial é aceita.
limitintegerOpcional8Número máximo de sugestões (1–15).
langstringOpcionalenCódigo de idioma para os rótulos.
latnumberOpcional-Latitude para direcionar resultados (opcional).
lonnumberOpcional-Longitude para direcionar resultados (opcional).
countrystringOpcional-Código de país ISO 3166-1 alpha-2, por exemplo AZ. Somente resultados desse país.
citystringOpcional-Filtro estrito de cidade, por exemplo Baku. Exige exatamente um código country.
osm_tagstringOpcional-Filtra as sugestões por tipo OSM, ex. place:city.

Filtros de país e cidade

Sem country, a busca é global. country=AZ limita os resultados ao Azerbaijão; country=AZ&city=Bakı a Baku no Azerbaijão. Sem correspondências, retorna HTTP 200 com uma lista vazia, sem ampliar a região. Cidade sem país ou código de país inválido retorna HTTP 400 InvalidGeocodeFilter. lat/lon afetam apenas a ordenação por proximidade. Registros sem cidade confirmada são excluídos quando há filtro de cidade.

Exemplos
GET /api/1/autocomplete?q=Nizami&country=AZ
GET /api/1/autocomplete?q=Nizami&country=AZ&city=Bak%C4%B1

HTTP 200: { "suggestions": [], "took": 12 }
HTTP 400: { "code": "InvalidGeocodeFilter", "error": "city requires exactly one country, for example country=AZ&city=Bakı." }

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Autocomplete API
curl "https://osrmroute.com/api/1/autocomplete?q=niz&lang=az&lat=40.40&lon=49.86" -H "Authorization: Bearer YOUR_KEY"

Limites e coordenadas

Custo em créditos: 1 credit

point=lat,lng; pontos JSON: [lat,lng]. Geometria GeoJSON: [lon,lat].

  • limit: 1–15
  • city: exactly 1 country

Sem correspondências, uma resposta bem-sucedida pode conter uma lista vazia. Os filtros de país/cidade não são alargados. O detalhe dos endereços depende do índice.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "suggestions": [
    {
      "name": "Nizami Street",
      "city": "Baku",
      "country": "Azerbaijan",
      "countrycode": "AZ",
      "point": {
        "lat": 40.3777,
        "lng": 49.8516
      },
      "label": "Nizami Street, Baku, Azerbaijan"
    }
  ],
  "took": 12
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "error": "The \"q\" parameter (search text) is required."
}

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "code": "InvalidGeocodeFilter",
  "error": "city requires exactly one country, for example country=AZ&city=Bakı."
}

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 até 100 endereços por requisição. Os resultados seguem a ordem de entrada, e cada endereço custa um crédito.

POST
/api/1/geocode/batch

Parâmetros (Query Params)

ParâmetroTipoStatusPadrãoDescrição
queriesarrayObrigatório[]Array de endereços a geocodificar (máx. 100).
langstringOpcionalenCódigo de idioma para os rótulos.
limitintegerOpcional1Máximo de correspondências por consulta (1–5).

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Batch Geocoding API
curl -X POST "https://osrmroute.com/api/1/geocode/batch" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queries":["Nizami küçəsi 10","28 May, Bakı"],"lang":"az"}'

Limites e coordenadas

Custo em créditos: 1 credit / query

Consulte os campos JSON; este pedido não requer um par de coordenadas.

  • queries: 1–100
  • limit: 1–5 / query
  • credits = queries.length

Sem correspondências, uma resposta bem-sucedida pode conter uma lista vazia. Os filtros de país/cidade não são alargados. O detalhe dos endereços depende do índice.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "results": [
    {
      "query": "Baku",
      "hits": [
        {
          "name": "Nizami Street",
          "city": "Baku",
          "country": "Azerbaijan",
          "countrycode": "AZ",
          "point": {
            "lat": 40.3777,
            "lng": 49.8516
          }
        }
      ]
    }
  ],
  "count": 1,
  "took": 12
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "error": "Body must include a non-empty \"queries\" array of address strings."
}

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "error": "A maximum of 100 queries can be geocoded per batch request."
}

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âmetroTipoStatusPadrãoDescrição
pointstringOpcional-Informe point=lat,lng ou os dois parâmetros lat e lon.
latnumberOpcional-Latitude (alternativa a point).
lonnumberOpcional-Longitude (alternativa a point).
timestampstringOpcionalnowTempo Unix (segundos) ou data ISO para resolver o deslocamento; padrão agora.

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Timezone API
curl "https://osrmroute.com/api/1/timezone?point=40.4093,49.8671" -H "Authorization: Bearer YOUR_KEY"

Limites e coordenadas

Custo em créditos: 1 credit

point=lat,lng; pontos JSON: [lat,lng]. Geometria GeoJSON: [lon,lat].

  • timestamp: Unix seconds | ISO 8601; default = now
  • utc_offset_seconds: seconds

Valide o formato de entrada e as unidades indicadas.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "timezone": "Asia/Baku",
  "point": {
    "lat": 40.3777,
    "lng": 49.8516
  },
  "utc_offset": "+04:00",
  "utc_offset_seconds": 14400,
  "dst": false,
  "abbreviation": "GMT+4",
  "local_time": "2026-01-01T16:00:00",
  "utc_time": "2026-01-01T12:00:00.000Z"
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "error": "Provide a valid coordinate via point=lat,lng or lat= & lon=."
}

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âmetroTipoStatusPadrãoDescrição
pointstringObrigatóriolat,lngCoordenada como lat,lng. Repita para cada ponto (até 100 no GET).

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Elevation API
curl "https://osrmroute.com/api/1/elevation?point=40.4093,49.8671&point=41.30,48.50" -H "Authorization: Bearer YOUR_KEY"

Limites e coordenadas

Custo em créditos: 1 credit / 10 points

point=lat,lng; pontos JSON: [lat,lng]. Geometria GeoJSON: [lon,lat].

  • GET: point count = 1–100
  • POST: points count = 1–1000
  • credits = max(1, ceil(points / 10))
  • elevation: number | null
  • GET with 1 point: elevation alias

A elevação pode ser null sem dados. Não substitua uma altura desconhecida por zero.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "results": [
    {
      "point": {
        "lat": 40.3777,
        "lng": 49.8516
      },
      "elevation": null
    }
  ],
  "unit": "meters"
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "error": "Provide at least one point=lat,lng (repeatable)."
}

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "error": "A maximum of 100 points can be queried per GET request; use POST for larger batches."
}

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âmetroTipoStatusPadrãoDescrição
pointstringObrigatóriolat,lngCoordenada como lat,lng.
polygonbooleanOpcionalfalsetrue para também retornar o limite como GeoJSON.
langstringOpcionalenCódigo de idioma para os nomes.

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Boundary Lookup API
curl "https://osrmroute.com/api/1/boundary?point=40.4093,49.8671" -H "Authorization: Bearer YOUR_KEY"

Limites e coordenadas

Custo em créditos: 1 credit

point=lat,lng; pontos JSON: [lat,lng]. Geometria GeoJSON: [lon,lat].

  • polygon: true | false
  • HTTP 422: BoundaryCoverageUnavailable

Os limites detalhados só existem nos conjuntos regionais aceites. Outros pontos devolvem BoundaryCoverageUnavailable.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "point": {
    "lat": 40.3777,
    "lng": 49.8516
  },
  "display_name": "Baku, Azerbaijan",
  "boundary_scope": "city",
  "country": "Azerbaijan",
  "countrycode": "AZ",
  "city": "Baku",
  "boundary": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          49.84,
          40.37
        ],
        [
          49.87,
          40.37
        ],
        [
          49.87,
          40.4
        ],
        [
          49.84,
          40.37
        ]
      ]
    ]
  }
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "error": "Provide a valid coordinate via point=lat,lng or lat= & lon=."
}

Não há dados administrativos detalhados aqui. Consulte a cobertura.

HTTP 422
{
  "code": "BoundaryCoverageUnavailable",
  "error": "Detailed administrative boundary data is not available at this coordinate."
}

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âmetroTipoStatusPadrãoDescrição
fencesarrayObrigatório[]Array de cercas: { id?, polygon:[[lat,lng],...] } ou { id?, center:[lat,lng], radius_m }. Até 100.
pointsarrayObrigatório[]Array de pontos [lat,lng] a testar (até 1000).

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Geofencing API
curl -X POST "https://osrmroute.com/api/1/geofence" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fences":[{"id":"zone1","polygon":[[40.40,49.85],[40.43,49.85],[40.43,49.90],[40.40,49.90]]}],"points":[[40.41,49.87],[40.50,50.10]]}'

Limites e coordenadas

Custo em créditos: 1 credit / 100 points

point=lat,lng; pontos JSON: [lat,lng]. Geometria GeoJSON: [lon,lat].

  • fences: 1–100
  • points: 1–1000
  • credits = max(1, ceil(points / 100))

Valide o formato de entrada e as unidades indicadas.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "results": [
    {
      "point": {
        "lat": 40.3777,
        "lng": 49.8516
      },
      "inside": [
        "depot"
      ]
    }
  ],
  "count": 1,
  "took": 1
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "error": "Body must include non-empty \"fences\" and \"points\" arrays."
}

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "error": "Limits: up to 100 fences and 1000 points per request."
}

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âmetroTipoStatusPadrãoDescrição
pointsarrayOpcional[]Array de pontos [lat,lng] do trajeto (>=2, até 2000).
polylinestringOpcional-Polyline codificada como alternativa a points.

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Elevation Profile API
curl -X POST "https://osrmroute.com/api/1/elevation/profile" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"points":[[40.37,49.85],[40.80,48.90],[41.30,48.05]]}'

Limites e coordenadas

Custo em créditos: 1 credit / 10 points

point=lat,lng; pontos JSON: [lat,lng]. Geometria GeoJSON: [lon,lat].

  • points: 2–2000
  • credits = max(1, ceil(points / 10))
  • elevation: number | null

A elevação pode ser null sem dados. Não substitua uma altura desconhecida por zero.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "profile": [
    {
      "point": {
        "lat": 40.3777,
        "lng": 49.8516
      },
      "elevation": null,
      "distance": 0
    },
    {
      "point": {
        "lat": 40.4,
        "lng": 49.86
      },
      "elevation": null,
      "distance": 2590
    }
  ],
  "total_ascent": 0,
  "total_descent": 0,
  "min_elevation": null,
  "max_elevation": null,
  "distance": 2590,
  "unit": "meters",
  "took": 12
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "error": "Provide a \"points\" array (>=2 [lat,lng]) or an encoded \"polyline\"."
}

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "error": "A maximum of 2000 points is allowed per request."
}

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âmetroTipoStatusPadrãoDescrição
pointstringObrigatóriolat,lngCoordenada como lat,lng.
datestringOpcionaltodayData (YYYY-MM-DD) a calcular; padrão hoje.

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Solar API
curl "https://osrmroute.com/api/1/solar?point=40.4093,49.8671&date=2026-07-07" -H "Authorization: Bearer YOUR_KEY"

Limites e coordenadas

Custo em créditos: 1 credit

point=lat,lng; pontos JSON: [lat,lng]. Geometria GeoJSON: [lon,lat].

  • date: YYYY-MM-DD; default = today
  • times: UTC ISO 8601 | null

As horas solares podem ser null no dia ou noite polar. As horas são UTC.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "point": {
    "lat": 40.3777,
    "lng": 49.8516
  },
  "date": "2026-01-01",
  "sunrise": "2026-01-01T04:00:00.000Z",
  "sunset": "2026-01-01T13:00:00.000Z",
  "solar_noon": "2026-01-01T08:30:00.000Z",
  "day_length_seconds": 32400
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "error": "Provide a valid coordinate via point=lat,lng or lat= & lon=."
}

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âmetroTipoStatusPadrãoDescrição
opstringObrigatóriodistanceOperação: distance, bearing, destination, midpoint, length, area, centroid, simplify, polyline_encode ou polyline_decode.
fromarrayOpcional[lat,lng]Ponto inicial [lat,lng].
toarrayOpcional[lat,lng]Ponto final [lat,lng].
patharrayOpcional[]Array de [lat,lng] (length/simplify/polyline_encode).
polygonarrayOpcional[]Anel [lat,lng] (area).
op → JSON
distance, bearing, midpoint → from, to
destination → from, bearing (°), distance_m
length → path (≥ 2)
area → polygon (≥ 3)
centroid → points (≥ 1)
simplify → path (2–2000), tolerance_m (10)
polyline_encode → path (≥ 1), precision (5)
polyline_decode → polyline, precision (5)

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Geometry Utilities API
curl -X POST "https://osrmroute.com/api/1/geometry" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"op":"distance","from":[40.37,49.85],"to":[40.40,49.86]}'

Limites e coordenadas

Custo em créditos: 1 credit

point=lat,lng; pontos JSON: [lat,lng]. Geometria GeoJSON: [lon,lat].

  • op: distance | bearing | destination | midpoint | length | area | centroid | simplify | polyline_encode | polyline_decode

Valide o formato de entrada e as unidades indicadas.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "op": "distance",
  "distance": 2590.25,
  "unit": "meters"
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "error": "Invalid geometry input for the requested op."
}

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âmetroTipoStatusPadrãoDescrição
pointstringOpcionallat,lngCoordenada lat,lng para converter em UTM/MGRS.
mgrsstringOpcional-String MGRS para converter de volta em coordenada.

Informe point=lat,lng, os dois parâmetros lat e lon, ou mgrs. Um mgrs não vazio tem prioridade. A conversão inversa retorna o centro da célula MGRS e omite utm.

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Coordinate Conversion API
curl "https://osrmroute.com/api/1/convert?point=40.3755,49.8516" -H "Authorization: Bearer YOUR_KEY"

Limites e coordenadas

Custo em créditos: 1 credit

point=lat,lng; pontos JSON: [lat,lng]. Geometria GeoJSON: [lon,lat].

  • point=lat,lng OR (lat=... AND lon=...) OR mgrs=...

Valide o formato de entrada e as unidades indicadas.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "point": {
    "lat": 40.3755,
    "lng": 49.8516
  },
  "mgrs": "39TVE0251070068",
  "utm": {
    "zone": 39,
    "band": "T",
    "easting": 402511,
    "northing": 4470068,
    "hemisphere": "N"
  }
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "error": "Provide point=lat,lng (or lat= & lon=), or mgrs= to reverse-convert."
}

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âmetroTipoStatusPadrãoDescrição
codestringOpcionalAZCódigo de país ISO 3166 alfa-2 ou alfa-3 (ex. AZ ou AZE).
namestringOpcional-Nome do país como alternativa ao código.

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Country Info API
curl "https://osrmroute.com/api/1/country?code=AZ" -H "Authorization: Bearer YOUR_KEY"

Limites e coordenadas

Custo em créditos: 1 credit

Consulte os campos JSON; este pedido não requer um par de coordenadas.

  • code=ISO2/ISO3 OR name=...

Valide o formato de entrada e as unidades indicadas.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "name": "Azerbaijan",
  "official_name": "Republic of Azerbaijan",
  "cca2": "AZ",
  "cca3": "AZE",
  "capital": "Baku",
  "region": "Asia",
  "subregion": "Western Asia",
  "currency": {
    "code": "AZN",
    "name": "Azerbaijani manat",
    "symbol": "₼"
  },
  "calling_code": "+994",
  "languages": [
    "Azerbaijani"
  ],
  "flag": "🇦🇿",
  "latlng": [
    40.5,
    47.5
  ]
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "error": "Provide code=ISO2/ISO3 or name=CountryName."
}

Use um código válido ou o nome exato do país.

HTTP 404
{
  "error": "Country not found."
}

Explicação da estrutura da resposta

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

Isochrone API

#

Estima a acessibilidade com base nos tempos de viagem até pontos de amostra. Se cada direção tiver um ponto alcançável, quality.status é estimated; caso contrário, é insufficient_data e polygons fica vazio. Um resultado vazio não prova que não existam vias alcançáveis. O limite é aproximado; apenas limites de tempo são suportados.

GET
/api/1/isochrone

Parâmetros (Query Params)

ParâmetroTipoStatusPadrãoDescrição
pointstringObrigatório-Ponto central. Formato: lat,lon.
time_limitintegerOpcional600Limite de tempo de viagem (em segundos).

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Isochrones API
curl "https://osrmroute.com/api/1/isochrone?point=40.4093,49.8671&time_limit=600" -H "Authorization: Bearer YOUR_KEY"

Limites e coordenadas

Custo em créditos: 2 credits / minute; minimum 10

point=lat,lng; pontos JSON: [lat,lng]. Geometria GeoJSON: [lon,lat].

  • time_limit: min = 60 s
  • time_limit ≤ plan.maxIsochroneMinutes × 60
  • quality.status = estimated | insufficient_data; polygons = [] when any bearing lacks a reachable sample
  • Sampled OSRM estimate, not an exact reachable-area boundary; an empty polygon does not prove no reachable roads
  • credits = max(10, ceil(time_limit_seconds / 30))

Os perfis de carro, caminhada e ciclismo são globais. Os pontos devem conectar-se por vias permitidas.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "quality": {
    "status": "estimated",
    "method": "sampled_osrm",
    "sampled_points": 80,
    "reachable_points": 48,
    "covered_bearings": 16,
    "total_bearings": 16,
    "unknown_points": 0
  },
  "polygons": [
    {
      "type": "Feature",
      "properties": {
        "bucket": 0,
        "time_limit": 600
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              49.84,
              40.37
            ],
            [
              49.87,
              40.37
            ],
            [
              49.87,
              40.4
            ],
            [
              49.84,
              40.37
            ]
          ]
        ]
      }
    }
  ]
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "error": "point parameter is required"
}

Verifique os limites de complexidade e as restrições da chave.

HTTP 403
{
  "error": "The Isochrone API is not available on your plan. Upgrade your plan to use it."
}

Escolha um perfil suportado. Não há mudança automática para carro.

HTTP 422
{
  "code": "ProfileNotAvailable",
  "error": "This travel profile is not available at one or more coordinates. No driving fallback was used."
}

O serviço ou a fonte estão indisponíveis. Repita com cuidado e pausas crescentes.

HTTP 504
{
  "code": "RoutingTimeout",
  "error": "The routing service did not respond within the request deadline. Retry later."
}

Explicação da estrutura da resposta

polygons[] — GeoJSON Feature; geometry — Polygon [lon,lat]; properties.time_limit — limite de tempo (s).

Route Optimization API

#

Planeja rotas com restrições de capacidade, janelas de tempo, habilidades e coletas/entregas vinculadas. Uma heurística com tempo limitado reduz a viagem sem garantir um ótimo global. Tarefas não atribuídas permanecem em solution.unassigned; entradas inválidas são rejeitadas por completo.

POST
/api/1/vrp

Parâmetros (Query Params)

ParâmetroTipoStatusPadrãoDescrição
vehiclesarrayOpcionalone default vehicleA lista de veículos — cada um com um id, capacidade opcional e um local de início como um array [lon, lat] (longitude primeiro).
servicesarrayOpcional[]As paradas a atender — cada uma com um id, um local como array [lon, lat] (longitude primeiro) e tempo de serviço opcional.
shipmentsarrayOpcional[]Tarefas vinculadas de coleta e entrega com amount e skills. Informe services, shipments ou ambos; no máximo 250 pontos de tarefa.
profilestringOpcionaldrivingPerfil comum: driving, cycling ou walking, incluindo os nomes alternativos documentados.

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Route Optimization API
curl -X POST "https://osrmroute.com/api/1/vrp" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vehicles":[{"vehicle_id":"v1","start":[49.85,40.37]}],"services":[{"id":10,"location":[49.86,40.40]}]}'

Limites e coordenadas

Custo em créditos: max(10, ceil(vehicles * task_points * 13 / 15)) credits

Arrays VRP start/location: [lon,lat]; objetos: lat e lng/lon. Tempo em segundos.

  • vehicles.length ≤ plan.maxVehicles
  • vehicles defaults to one vehicle when omitted
  • services.length + 2 × shipments.length ≤ 250; vehicles.length ≤ 100
  • task_points = services.length + 2 × shipments.length
  • credits = max(10, ceil(vehicles * task_points * 13 / 15)); invalid inputs are refunded
  • Capacity arrays, time_windows, skills and paired shipments are enforced; unsupported options return 400
  • solution.unassigned lists tasks not assigned by the bounded heuristic; this is not proof of infeasibility
  • transport_time is travel only; service_time, waiting_time and elapsed time are separate; costs is travel seconds

Os perfis de carro, caminhada e ciclismo são globais. Os pontos devem conectar-se por vias permitidas.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "status": "finished",
  "job_id": "opt-1234567890",
  "processing_time": 0,
  "solution": {
    "unassigned": [],
    "quality": {
      "solver": "vroom",
      "version": "1.15.0",
      "constraints_verified": true,
      "optimality_proven": false
    },
    "costs": 420,
    "distance": 3200,
    "time": 420,
    "no_vehicles": 1,
    "no_unassigned": 0,
    "routes": [
      {
        "vehicle_id": "v1",
        "distance": 3200,
        "transport_time": 420,
        "activities": [
          {
            "type": "start",
            "location_id": "depot",
            "end_time": 0
          },
          {
            "type": "service",
            "id": 10,
            "location_id": "stop_1",
            "arr_time": 200,
            "end_time": 200
          },
          {
            "type": "end",
            "location_id": "depot",
            "arr_time": 420
          }
        ]
      }
    ]
  }
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "code": "InvalidOptimizationInput",
  "error": "At least one service with valid coordinates is required."
}

Verifique os limites de complexidade e as restrições da chave.

HTTP 403
{
  "error": "Your plan allows up to 1 vehicles per request. Upgrade your plan for more."
}

Confira se os pontos estão perto de vias acessíveis e se as vias são conectadas para o perfil escolhido.

HTTP 422
{
  "code": "NoNearbyRoad",
  "error": "No connected route within 2000 metres of the requested coordinates."
}

Explicação da estrutura da resposta

status → finished; job_id — ID da tarefa; solution: distance — distância (m), time e costs — tempo (s), no_vehicles, no_unassigned — quantidades, routes[] — rotas. routes[]: vehicle_id, distance (m), transport_time (s), activities[] — atividades.

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âmetroTipoStatusPadrãoDescrição
customersarrayObrigatório[]Coordenadas de clientes e pesos a serem agrupados em clusters.

Exemplo de pedido

Substitua YOUR_KEY pela sua chave API. Os pedidos consomem créditos; copiar o exemplo não envia um pedido.

Agrupamento de locais
curl -X POST "https://osrmroute.com/api/1/cluster" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customers":[[49.85,40.37],[49.86,40.40],[49.83,40.39]],"clusters":2}'

Limites e coordenadas

Custo em créditos: 3 credits

Coordenadas de clientes de entrada: [lon,lat]; centro de saída: [lat,lon].

  • customers: valid coordinates ≥ 1
  • 1 ≤ clusters ≤ valid_customers.length

Valide o formato de entrada e as unidades indicadas.

Planos e preços atuaisCobertura por serviço

Exemplo de resposta JSON

JSON ilustrativo e abreviado. Os valores, campos opcionais e dados do mapa podem variar. As distâncias são em metros e os tempos de rota em segundos, salvo indicação contrária.

HTTP 200 · application/json
{
  "status": "finished",
  "job_id": "cluster-1234567890",
  "processing_time": 0,
  "no_clusters": 1,
  "clusters": [
    {
      "ids": [
        "s1",
        "s2"
      ],
      "center": [
        40.385,
        49.855
      ],
      "size": 2
    }
  ]
}
Erros do serviço

Corrija os parâmetros em falta ou inválidos.

HTTP 400
{
  "error": "Provide a \"customers\" array with valid coordinates."
}

Explicação da estrutura da resposta

status → finished; job_id — ID da tarefa; no_clusters — número de grupos; clusters[]: ids[] — elementos, center [lat,lon] — centro, size — dimensão.

Endpoints de compatibilidade

Antes de migrar uma integração, confira a ordem das coordenadas e as unidades da resposta.

A URL abreviada de Routing usa a mesma entrada e saída do OSRM. A Route antiga recebe pares latitude,longitude repetidos. paths[].time está em milissegundos e paths[].distance em metros. Route info descreve a cobertura configurada e custa um crédito.

HTTP
GET /api/v1/route/driving/49.8516,40.3755;49.8378,40.3892
GET /api/1/route?point=40.3755,49.8516&point=40.3892,49.8378
GET /api/1/route/info

A Matrix antiga aceita parâmetros point repetidos ou listas from_point e to_point. Em JSON, envie from_points e to_points como pares latitude,longitude. Tempos em milissegundos e distâncias em metros.

HTTP
GET /api/1/matrix?point=40.3755,49.8516&point=40.3892,49.8378
POST /api/1/matrix · POST /api/1/matrix/calculate
{"from_points":[[40.3755,49.8516]],"to_points":[[40.3892,49.8378]]}

A Match antiga recebe um trajeto GPS ordenado em pares [lon, lat]. Você pode enviar tempo em segundos e raio em metros por ponto. A resposta usa distâncias em metros e tempos em milissegundos. Elevation ([lat, lon]) em lote aceita até 1.000 pares e retorna metros ou null.

POST /api/1/match
{"points":[[49.8516,40.3755],[49.8378,40.3892]],"timestamps":[1760000000,1760000120],"radiuses":[20,20]}
POST /api/1/elevation
{"points":[[40.3755,49.8516],[40.3892,49.8378]]}

optimize e vrp/optimize usam o formato VRP. Os aliases de agrupamento e geocodificação em lote usam os formatos principais. VRP e agrupamento retornam o resultado diretamente.

Playground do mapa

SDK oficiais

Kotlin para Android/JVM e Swift para iOS. Modelos tipados e pedidos assíncronos para as APIs geográficas OSRMRoute.

JavaScript / TypeScriptPythonKotlin / AndroidSwift / iOSVer os SDK

Suporte OSRMRoute

Escreva diretamente à nossa equipa

ESTAMOS PARA AJUDAR

Como podemos ajudar?

Envie uma mensagem. As respostas aos pedidos também são enviadas para o seu email verificado.

Suas conversas

Suas conversas aparecerão aqui.