Documentación de la API y Playground

Clave de prueba:YOUR_API...

Introducción

La OSRMRoute Directions API es un servicio web RESTful creado para integrar enrutamiento geoespacial rápido y de alto rendimiento, matrices de viaje, búsqueda de direcciones (geocodificación) y optimización de rutas en tus aplicaciones. Esta documentación explica en detalle todas las capacidades de la API, los parámetros y los pasos de integración.

Autenticación

Las solicitudes a la API de OSRMRoute usan una clave API única para la autenticación. Puedes añadir tu clave API a cada solicitud como parámetro de consulta (?key=YOUR_KEY) o mediante la cabecera HTTP Authorization (como token Bearer).

GETAny endpoint

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
key	string	Obligatorio	-	La clave API única obtenida de tu panel personal. Esta clave determina los límites de tus solicitudes.

Códigos de error

OSRMRoute usa códigos de estado HTTP estándar y mensajes de error JSON detallados para indicar el estado de una solicitud.

Explicación de la estructura de la respuesta

Principales códigos de estado y su significado: - **200 OK**: La solicitud se completó correctamente. - **400 Bad Request**: Los parámetros son inválidos o faltan. - **401 Unauthorized**: La clave API no se proporcionó o es inválida. - **403 Forbidden**: La clave API está bloqueada o inactiva. - **429 Too Many Requests**: Se superó el límite diario de créditos. - **500 Internal Error**: Ocurrió un error interno del sistema.

Routing API

Calcula la ruta más rápida y corta del punto A al punto B (con puntos intermedios via). Devuelve instrucciones paso a paso (turn-by-turn) y geometría GeoJSON para diferentes perfiles de transporte (driving, cycling, walking).

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

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
profile	string	Obligatorio	driving	Perfil de modo de transporte. Valores admitidos: driving (coche), cycling (bici), walking (peatón).
coordinates	string	Obligatorio	-	Coordenadas de los puntos. Formato: lon,lat;lon,lat;lon,lat... (al menos 2 puntos).
overview	string	Opcional	full	Nivel de detalle de la geometría de ruta devuelta: simplified (simplificada), full (geometría completa), false (sin geometría).
geometries	string	Opcional	geojson	Formato de geometría: geojson (objeto GeoJSON), polyline (cadena codificada).
steps	boolean	Opcional	true	Si se devuelven instrucciones paso a paso para cada giro.

Explicación de la estructura de la respuesta

Una respuesta correcta contiene la distancia total de la ruta (en metros), la duración del viaje (en segundos), los puntos de paso y la línea de ruta en GeoJSON.

Matrix API

Calcula una matriz rápida de distancia y tiempo de viaje entre varios puntos (una tabla NxM). Una herramienta ideal para optimizar rutas logísticas.

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

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
profile	string	Obligatorio	driving	Perfil de transporte (driving, cycling, walking).
coordinates	string	Obligatorio	-	Puntos de la matriz. Formato: lon,lat;lon,lat;lon,lat...
annotations	string	Opcional	duration,distance	Datos a calcular: duration (tiempo), distance (distancia) o ambos.

Explicación de la estructura de la respuesta

Una respuesta correcta devuelve una tabla-matriz bidimensional de distances (distancias) y durations (duraciones) para cada combinación de punto de inicio y fin.

Map Matching API

Ajusta trazas GPS imprecisas a la red vial real (snap to road). Se usa para limpiar el ruido en las señales GPS.

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

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
profile	string	Obligatorio	driving	Perfil de transporte.
coordinates	string	Obligatorio	-	La secuencia de coordenadas GPS a ajustar (lon,lat;lon,lat...)
overview	string	Opcional	full	Precisión de la geometría de la ruta ajustada.

Nearest API

Ajusta cualquier coordenada al segmento de carretera real más cercano (snap) y devuelve información sobre el nombre de la vía.

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

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
profile	string	Obligatorio	driving	Perfil de transporte.
coordinates	string	Obligatorio	-	El punto cerca del cual buscar. Formato: lon,lat (un solo par).
number	integer	Opcional	3	El número de carreteras candidatas más cercanas a encontrar.

Trip API

Resuelve el Problema del Viajante (TSP): encuentra la ruta circular (o abierta) más óptima para visitar un conjunto de puntos dado y ordena los puntos.

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

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
profile	string	Obligatorio	driving	Perfil de transporte.
coordinates	string	Obligatorio	-	Puntos a visitar. Formato: lon,lat;lon,lat...
source	string	Opcional	any	El punto desde el que puede empezar la ruta (any o el primer punto).
destination	string	Opcional	any	El punto donde termina la ruta (any o el último punto).

Directions API

Devuelve navegación paso a paso entre dos o más puntos con una lista de instrucciones limpia (texto, distancia, duración, tipo de maniobra y ubicación). Admite coche, bici y a pie, además de hasta 3 rutas alternativas en una sola llamada.

GET/api/1/directions

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
point	string	Obligatorio	lat,lng	Punto como lat,lng. Repite el parámetro por cada parada (mínimo 2).
profile	string	Opcional	driving	Modo de transporte: driving, cycling o walking.
alternatives	integer	Opcional	0	Número de rutas alternativas adicionales a devolver (0–3).
lang	string	Opcional	en	Código de idioma para el texto de las instrucciones.

Explicación de la estructura de la respuesta

Devuelve { code, profile, routes[], waypoints[] }. Cada ruta tiene distance (m), duration (s), una geometría GeoJSON y un array instructions[]; cada instrucción incluye text, type, modifier, distance, duration, name y location [lat,lng].

Snap to Road API

Ajusta puntos GPS crudos e imprecisos a la posición más cercana de la red vial. Repite el parámetro point por cada coordenada (hasta 100).

GET/api/1/snap

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
point	string	Obligatorio	lat,lng	Punto GPS como lat,lng. Repite el parámetro por cada punto (máximo 100).
profile	string	Opcional	driving	Red vial a la que ajustar: driving, cycling o walking.

Explicación de la estructura de la respuesta

Devuelve { code, profile, snapped[] }. Cada elemento incluye el input original [lat,lng], la posición ajustada [lat,lng], la distancia de ajuste en metros y el nombre de la vía.

Geocoding API

Convierte un texto de búsqueda en coordenadas geográficas (directa) o coordenadas en una dirección (inversa). Autocompletado rápido y tolerante a errores tipográficos que cubre calles, direcciones y puntos de interés (cafés, tiendas, hoteles, oficinas). Ideal para buscar mientras se escribe.

GET/api/1/geocode

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
q	string	Obligatorio	-	La dirección a buscar (p. ej.: «Calle Nizami, Bakú»).
reverse	boolean	Opcional	false	Debe ser true para realizar geocodificación inversa (búsqueda de coordenada a dirección).
point	string	Opcional	lat,lng	Coordenada (lat,lng) para geocodificación inversa a una dirección. Obligatorio cuando reverse=true.
limit	integer	Opcional	5	Número máximo de resultados a devolver (1–20, por defecto 5).
lang	string	Opcional	en	Idioma preferido para los nombres de resultados (p. ej. en, az, ru). Por defecto en.
lat	number	Opcional	-	Latitud para sesgar los resultados (los cercanos primero). Junto con lon.
lon	number	Opcional	-	Longitud para sesgar los resultados. Junto con lat.
bbox	string	Opcional	-	Limitar resultados a un cuadro: minLon,minLat,maxLon,maxLat.
osm_tag	string	Opcional	-	Filtrar por etiqueta OSM, p. ej. place (localidades) o amenity:cafe. Prefijo ! para excluir.
city	string	Opcional	-	Prioriza los resultados de esta ciudad (p. ej. Bakı) sin ocultar los demás.
elastic	boolean	Opcional	true	Búsqueda elástica (difusa, alta cobertura) — true por defecto. Tolera erratas, falta de diacríticos (ə↔e), orden de palabras, palabras genéricas (metro, rayonu) y números de casa. false para coincidencia estricta.

Ejemplos

# Sesgar a una ubicación, solo localidades
GET /api/1/geocode?q=qala&lat=40.41&lon=49.87&osm_tag=place&key=YOUR_KEY

# Priorizar una ciudad arriba
GET /api/1/geocode?q=market&city=Bakı&key=YOUR_KEY

# Geocodificación inversa (coordenadas a dirección)
GET /api/1/geocode?reverse=true&point=40.409,49.867&key=YOUR_KEY

Lugares (POI cercanos)

Encuentra puntos de interés cerca de una ubicación — cafés, tiendas, hoteles, cajeros, farmacias y más — filtrados por categoría y radio, ordenados por distancia.

GET/api/1/places

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
point	string	Obligatorio	lat,lng	Coordenada central lat,lng para buscar (obligatorio).
radius	number	Opcional	1	Radio de búsqueda en kilómetros (0.05–20, por defecto 1).
category	string	Opcional	-	Filtro por etiqueta OSM, p. ej. amenity:cafe, shop, tourism:hotel. Prefijo ! para excluir. Vacío = todos los POI.
limit	integer	Opcional	10	Máx. resultados (1–50, por defecto 10).
lang	string	Opcional	en	Idioma preferido para los nombres (p. ej. en, az, ru).

Autocomplete API

Sugerencias de lugares rápidas y tolerantes a errores mientras el usuario escribe, con sesgo por ubicación.

GET/api/1/autocomplete

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
q	string	Obligatorio	-	Texto de búsqueda — se admite entrada parcial.
limit	integer	Opcional	8	Número máximo de sugerencias (1–15).
lang	string	Opcional	en	Código de idioma para las etiquetas.
lat	number	Opcional	-	Latitud para sesgar resultados (opcional).
lon	number	Opcional	-	Longitud para sesgar resultados (opcional).
osm_tag	string	Opcional	-	Filtra las sugerencias por tipo OSM, p. ej. place:city.

Explicación de la estructura de la respuesta

Devuelve { suggestions[], took }. Cada sugerencia tiene label, name, city, state, country, countrycode, type, osm_id y point {lat,lng}.

Batch Geocoding API

Geocodifica cientos de direcciones en una sola petición — ideal para pipelines de datos e importaciones.

POST/api/1/geocode/batch

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
queries	array	Obligatorio	[]	Array de direcciones a geocodificar (máx. 100).
lang	string	Opcional	en	Código de idioma para las etiquetas.
limit	integer	Opcional	1	Coincidencias máximas por consulta (1–5).

Explicación de la estructura de la respuesta

Devuelve { results[], count, took }. Cada resultado empareja la consulta de entrada con un array hits[]; cada coincidencia incluye label, city, country y point {lat,lng}. Se conserva el orden de entrada.

Timezone API

Zona horaria IANA, desfase UTC actual, estado del horario de verano y hora local para cualquier coordenada.

GET/api/1/timezone

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
point	string	Obligatorio	lat,lng	Coordenada como lat,lng.
lat	number	Opcional	-	Latitud (alternativa a point).
lon	number	Opcional	-	Longitud (alternativa a point).
timestamp	integer	Opcional	now	Hora Unix (segundos) o fecha ISO para resolver el desfase; por defecto ahora.

Explicación de la estructura de la respuesta

Devuelve { timezone, point, utc_offset, utc_offset_seconds, dst, abbreviation, local_time, utc_time }. utc_offset es una cadena +HH:MM, dst es true cuando rige el horario de verano y local_time es una marca ISO con el desfase de la zona.

Elevation API

Altura sobre el nivel del mar, en metros, para cualquier coordenada — un punto o el perfil de toda una ruta.

GET/api/1/elevation

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
point	string	Obligatorio	lat,lng	Coordenada como lat,lng. Repite por cada punto (hasta 100 en GET).

Explicación de la estructura de la respuesta

Devuelve { results[], unit:"meters" }, donde cada resultado es { point:{lat,lng}, elevation }. elevation son metros sobre el nivel del mar (null si se desconoce, 0 sobre el mar). Para un solo punto también se incluye elevation en el nivel superior. Para lotes grandes, POST { points:[[lat,lng],...] } (hasta 1000).

Boundary Lookup API

Averigua en qué país, estado, ciudad y distrito cae una coordenada — con el polígono de límite si se solicita.

GET/api/1/boundary

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
point	string	Obligatorio	lat,lng	Coordenada como lat,lng.
polygon	boolean	Opcional	false	true para devolver también el límite como GeoJSON.
lang	string	Opcional	en	Código de idioma para los nombres.

Explicación de la estructura de la respuesta

Devuelve { point, display_name, country, countrycode, state, county, city, district, postcode, osm_id, osm_type } y, con polygon=true, una geometría de límite GeoJSON.

Geofencing API

Comprueba en una llamada en cuáles de tus zonas cae cada punto — vallas poligonales o circulares.

POST/api/1/geofence

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
fences	array	Obligatorio	[]	Array de vallas: { id?, polygon:[[lat,lng],...] } o { id?, center:[lat,lng], radius_m }. Hasta 100.
points	array	Obligatorio	[]	Array de puntos [lat,lng] a comprobar (hasta 1000).

Explicación de la estructura de la respuesta

Devuelve { results[], count }. Cada resultado es { point:{lat,lng}, inside:[fenceId,...] } con todas las vallas en las que cae el punto (vacío si ninguna).

Elevation Profile API

Altitud en cada punto de una ruta más ascenso, descenso y distancia totales — un perfil completo.

POST/api/1/elevation/profile

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
points	array	Obligatorio	[]	Array de puntos [lat,lng] de la ruta (>=2, hasta 2000).
polyline	string	Opcional	-	Polyline codificada como alternativa a points.

Explicación de la estructura de la respuesta

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

Solar API

Amanecer, atardecer, crepúsculo, mediodía solar y duración del día para cualquier coordenada y fecha.

GET/api/1/solar

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
point	string	Obligatorio	lat,lng	Coordenada como lat,lng.
date	string	Opcional	today	Fecha (YYYY-MM-DD) a calcular; por defecto hoy.

Explicación de la estructura de la respuesta

Devuelve { point, date, sunrise, sunset, solar_noon, dawn, dusk, golden_hour, night_start, night_end, day_length_seconds }. Horas en UTC ISO; null en día/noche polar.

Geometry Utilities API

Distancia, rumbo, área, centroide, simplificación y polyline encode/decode — matemática espacial como servicio.

POST/api/1/geometry

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
op	string	Obligatorio	distance	Operación: distance, bearing, destination, midpoint, length, area, centroid, simplify, polyline_encode o polyline_decode.
from	array	Opcional	[lat,lng]	Punto inicial [lat,lng].
to	array	Opcional	[lat,lng]	Punto final [lat,lng].
path	array	Opcional	[]	Array de [lat,lng] (length/simplify/polyline_encode).
polygon	array	Opcional	[]	Anillo [lat,lng] (area).

Explicación de la estructura de la respuesta

Devuelve { op, ... } con el resultado de la operación, p. ej. { distance, unit }, { bearing_deg }, { point }, { area, unit }, { path } o { polyline }.

Coordinate Conversion API

Convierte latitud/longitud a y desde referencias de cuadrícula UTM y MGRS.

GET/api/1/convert

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
point	string	Obligatorio	lat,lng	Coordenada lat,lng para convertir a UTM/MGRS.
mgrs	string	Opcional	-	Cadena MGRS para convertir de vuelta a coordenada.

Explicación de la estructura de la respuesta

Devuelve { point, mgrs, utm:{ zone, band, easting, northing, hemisphere } }. Con mgrs= devuelve { mgrs, point }.

Country Info API

Moneda, código telefónico, idiomas, capital y bandera de cualquier país por código ISO o nombre.

GET/api/1/country

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
code	string	Obligatorio	AZ	Código de país ISO 3166 alfa-2 o alfa-3 (p. ej. AZ o AZE).
name	string	Opcional	-	Nombre del país como alternativa al código.

Explicación de la estructura de la respuesta

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

Isochrone API

Devuelve polígonos de las zonas geográficas alcanzables desde un punto dado dentro de un tiempo o distancia determinados.

GET/api/1/isochrone

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
point	string	Obligatorio	-	Punto central. Formato: lat,lon.
time_limit	integer	Opcional	600	Límite de tiempo de viaje (en segundos).

Route Optimization API

Optimiza las rutas de una flota de vehículos (Vehicle Routing Problem). Calcula el plan de entrega y transporte de los vehículos con el menor coste.

POST/api/1/vrp

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
vehicles	array	Obligatorio	[]	La lista de vehículos — cada uno con un id, capacidad opcional y una ubicación de inicio como un array [lon, lat] (longitud primero).
services	array	Obligatorio	[]	Las paradas a atender — cada una con un id, una ubicación como un array [lon, lat] (longitud primero) y un tiempo de servicio opcional. Mismo orden de coordenadas que en todos nuestros endpoints.

Location Clustering API

Agrupa (agrupa en clústeres) las coordenadas dadas según su proximidad y densidad geográfica.

POST/api/1/cluster

Parámetros (Query Params)

Parámetro	Tipo	Estado	Predeterminado	Descripción
customers	array	Obligatorio	[]	Coordenadas de clientes y pesos a agrupar en clústeres.

SDK oficiales

Cero dependencias, totalmente tipado, todos los endpoints. Haz tu primera llamada en menos de un minuto.

osrmrouteosrmrouteVer los SDK