API de mapas, búsqueda y Studio

Desarrolla con mapas y datos geográficos

Autenticación y errores

Envía la clave en Authorization: Bearer. Coordenadas: [longitud, latitud]. Configura OSRMROUTE_API_KEY localmente; DATASET_ID es el UUID de un conjunto propio. Nunca publiques una clave Studio en el navegador.

401: clave inválida · 403: sin permiso · 402: créditos insuficientes · 429: límite de solicitudes · 502/503: fuente no disponible. Comprueba el estado HTTP; las operaciones de pago fallidas liberan sus créditos reservados.

409: conflicto de revisión. Lee el recurso actual y concilia los cambios antes de reintentar.

Búsqueda en lenguaje natural

Encuentre lugares con una consulta breve en inglés.

Créditos por solicitud: 2
Permisos necesarios: geocode + places

Categoría en inglés + near/in + lugar; radio de 100–5000 m. Seis categorías, hasta diez candidatos. Sin valoraciones, precios ni disponibilidad en directo. Dos créditos incluso por resultados vacíos correctos.

POST /api/v1/search/natural

Cuerpo de solicitud — Los campos * son obligatorios.
`q *`	`string`	`maxLength: 1000`
`ai`	`boolean`	`default: false`
`center`	`array`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/search/natural" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"cafes near Berlin within 2 km"}'

Respuesta

intent
places[].distance_meters
places[].details
interpretation: constrained_english_grammar
exhaustive: false

Explorar la API Referencia API

Detalles de lugares

Consulte atributos proporcionados por la fuente.

Créditos por solicitud: 1
Permisos necesarios: places

Un crédito con permiso places. Objeto OpenStreetMap por ID del resultado; caché fuente de una hora. Datos de contacto, horarios y accesibilidad ausentes quedan null. La fecha fuente es la edición del objeto, no verificación comercial. Sin estado de apertura en directo. 20 llamadas/min/clave; 30 lecturas fuente/min globales sin caché.

POST /api/v1/places/details

Cuerpo de solicitud — Los campos * son obligatorios.
`id *`	`string`	`maxLength: 24`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/places/details" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"osm:N:123"}'

Respuesta

place.details.phone
place.details.website
place.details.opening_hours
place.details.wheelchair
place.details.observed_at
place.details.source_updated_at
place.details.open_now: null

Explorar la API Referencia API

Vista previa de estilo por texto

Describa colores y capas y revise el mapa.

Créditos por solicitud: 0
Permisos necesarios: studio

Comandos en inglés separados por punto y coma: tema, color hex y visibilidad. La vista previa no guarda. Aplicar modifica el borrador y puede guardarlo automáticamente.

POST /api/v1/studio/preview

Cuerpo de solicitud — Los campos * son obligatorios.
`prompt *`	`string`	`maxLength: 1000`
`ai`	`boolean`	`default: false`
`design`	`object`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/studio/preview" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"dark; water #123456; hide buildings"}'

Respuesta

design
changes[]
saved: false
method: explicit_style_commands

Explorar la API Referencia API

Static Maps API

Exporta mapas con estilo como PNG para informes y aplicaciones.

Créditos por solicitud: 4
Permisos necesarios: maps

Cuatro paletas: light, dark, navigation, minimal. 128–512 px, zoom 1–14. Renderizado simplificado con atribución; sin capas ni efectos personalizados de Studio.

POST /api/v1/maps/static

Cuerpo de solicitud — Los campos * son obligatorios.
`center *`	`array`
`zoom`	`integer`	`min: 1 · max: 14 · default: 12`
`width`	`integer`	`min: 128 · max: 512 · default: 512`
`height`	`integer`	`min: 128 · max: 512 · default: 512`
`style`	`string`	`light \| dark \| navigation \| minimal`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/maps/static" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"center":[13.405,52.52],"zoom":12,"width":512,"height":512,"style":"light"}' \
  --output map.png

Respuesta

Content-Type: image/png

Explorar la API Referencia API

Dataset Query API

Encuentra objetos cercanos en tus propios datos geográficos.

Créditos por solicitud: 1
Permisos necesarios: maps

Solo conjuntos del propietario de la clave. Radio 0–50.000 m, límite 1–50. Puntos cercanos y distancias locales estimadas, no distancia por carretera ni geometrías completas. Los resultados vacíos correctos también cuestan 1 crédito.

POST /api/v1/maps/datasets/{id}/query

Cuerpo de solicitud — Los campos * son obligatorios.
`point *`	`array`
`radius`	`number`	`min: 0 · max: 50000 · default: 0`
`limit`	`integer`	`min: 1 · max: 50 · default: 10`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/maps/datasets/$DATASET_ID/query" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"point":[2.3522,48.8566],"radius":1000,"limit":10}'

Respuesta

type: FeatureCollection
features[].geometry.type: Point
features[].properties
returned

Explorar la API Referencia API

Search Along Route API

Compara paradas y tiempo de conducción adicional en una ruta.

Créditos por solicitud: 14
Permisos necesarios: places + route

Rutas de conducción de hasta 200 km. Cinco posiciones muestreadas y hasta ocho desvíos; búsqueda no exhaustiva. fuel, charging_station, restaurant, cafe, parking, pharmacy. Sin tráfico en directo ni disponibilidad de cargadores.

POST /api/v1/places/along-route

Cuerpo de solicitud — Los campos * son obligatorios.
`start *`	`array`
`end *`	`array`
`category *`	`string`	`fuel \| charging_station \| restaurant \| cafe \| parking \| pharmacy`
`max_detour_seconds`	`number`	`min: 0 · max: 1800 · default: 600`
`limit`	`integer`	`min: 1 · max: 8 · default: 5`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/places/along-route" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start":[13.405,52.52],"end":[13.3777,52.5163],"category":"cafe","max_detour_seconds":600,"limit":5}'

Respuesta

places[]
baseline.duration_seconds
baseline.distance_meters
discovery
duration_model

Explorar la API Referencia API

Structured Geocoding API

Busca direcciones por calle, ciudad, código postal y país.

Créditos por solicitud: 1
Permisos necesarios: geocode

Incluye street, city o postcode. País de dos letras; otros campos hasta 100 caracteres. Los componentes forman una búsqueda textual. matched/different/missing y precisión de origen no garantizan validación postal.

POST /api/v1/search/structured

Cuerpo de solicitud — Los campos * son obligatorios.
`housenumber`	`string`	`maxLength: 100`
`street`	`string`	`maxLength: 100`
`city`	`string`	`maxLength: 100`
`state`	`string`	`maxLength: 100`
`postcode`	`string`	`maxLength: 100`
`countrycode`	`string`	`maxLength: 2`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/search/structured" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"street":"Friedrichstraße","city":"Berlin","countrycode":"DE"}'

Respuesta

features[].id
features[].address
features[].precision
features[].match.components
features[].precision_basis
search_method: composed_address_query

Explorar la API Referencia API

Suggest & Retrieve API

Crea búsquedas de lugares con sugerencias y recuperación segura.

Créditos por solicitud: 1 + 1
Permisos necesarios: geocode

Suggest y retrieve cuestan 1 crédito cada uno. Consulta de 1–200 caracteres. Tokens de 10 minutos vinculados al propietario. Retrieve devuelve la instantánea firmada, no una nueva búsqueda.

POST /api/v1/search/suggest

Cuerpo de solicitud — Los campos * son obligatorios.
`q *`	`string`	`maxLength: 200`

POST /api/v1/search/retrieve

Cuerpo de solicitud — Los campos * son obligatorios.
`token *`	`string`	`maxLength: 16384`

cURL

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/search/suggest" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"Paris"}'

Respuesta

suggestions[].id
suggestions[].name
suggestions[].address
suggestions[].token
expires_in_seconds: 600

retrieve → place, retrieval: signed_suggestion_snapshot

cURL · retrieve

curl --fail-with-body -X POST "https://osrmroute.com/api/v1/search/retrieve" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token":"TOKEN_FROM_SUGGEST"}'

Explorar la API Referencia API

Studio API

Gestiona estilos, conjuntos de datos y publicación desde tu aplicación.

Créditos por solicitud: 0
Permisos necesarios: studio

Permiso studio explícito, incluso con claves sin restricciones. GET lista estilos o metadatos; POST gestiona recursos. Estilos con revisiones y confirmación de publicación. Datos: crear/eliminar, sin edición directa. 30 lecturas o 5 escrituras/minuto/clave; se aplican cuotas del espacio.

GET / POST /api/v1/studio/{resource}

Cuerpo de solicitud — Los campos * son obligatorios.
`action *`	`string`
`id`	`string`
`revision`	`integer`
`name`	`string`	`maxLength: 80`
`design`	`object`
`data`	`object`
`confirmPublic`	`boolean`
`confirmDelete`	`boolean`
`version`	`integer`

cURL

curl --fail-with-body "https://osrmroute.com/api/v1/studio/styles" \
  -H "Authorization: Bearer $OSRMROUTE_API_KEY"

Respuesta

GET styles → styles[]
GET datasets → datasets[]

Acciones de Studio
`styles · create`	`name, design`
`styles · save / autosave`	`id, revision, name, design`
`styles · duplicate`	`id, revision, name`
`styles · restore`	`id, revision, version`
`styles · publish`	`id, revision, confirmPublic: true`
`styles · unpublish / delete`	`id, revision`
`datasets · create`	`name, data: GeoJSON FeatureCollection`
`datasets · delete`	`id, confirmDelete: true`

POST /api/v1/studio/styles · application/json

{
  "action": "create",
  "name": "Berlin",
  "design": {
    "preset": "light",
    "colors": {
      "land": "#f1f3f5",
      "water": "#a9d8ed",
      "park": "#c9dfc6",
      "road": "#ffffff",
      "highway": "#edc779",
      "building": "#d9dee3",
      "label": "#334155"
    },
    "visible": {
      "roads": true,
      "buildings": true,
      "parks": true,
      "labels": true,
      "pois": true,
      "boundaries": true
    },
    "center": [
      13.405,
      52.52
    ],
    "zoom": 11,
    "overlays": []
  }
}

POST /api/v1/studio/datasets · application/json

{
  "action": "create",
  "name": "Paris places",
  "data": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "properties": {
          "name": "Paris"
        },
        "geometry": {
          "type": "Point",
          "coordinates": [
            2.3522,
            48.8566
          ]
        }
      }
    ]
  }
}

Explorar la API Referencia API

API de mapas, búsqueda y Studio

Autenticación y errores

Búsqueda en lenguaje natural

Detalles de lugares

Vista previa de estilo por texto

Static Maps API

Dataset Query API

Search Along Route API

Structured Geocoding API

Suggest & Retrieve API

Studio API

Soporte OSRMRoute

¿Cómo podemos ayudarle?