Migrate from OSRM to Mapricot

This guide moves an app's OSRM calls to Mapricot, whether they go to your own OSRM server or a public one. It lists the Mapricot endpoint for each OSRM service, how each parameter and response field carries over, and what has no equivalent. To weigh up the switch first, see Mapricot vs OSRM.

Mapricot's API isn't compatible with OSRM's, so each call changes. Both route on OpenStreetMap roads. The main differences are that Mapricot takes the stops in a JSON body as named lat and lon, rather than lon,lat pairs in the URL, and that its steps come with written instructions.

Migrate with a coding agent

Paste this prompt into Claude Code, Cursor, Codex, or another coding agent, in your project. It finds your OSRM calls, plans the switch with you, and makes it.

Prompt
Migrate this project from OSRM to Mapricot, a location API. https://mapricot.com/guides/migrate-from-osrm/ maps each OSRM service, parameter, and response field to Mapricot's, and https://mapricot.com/llms.txt lists Mapricot's docs.

1. Find every use of OSRM in this project: requests to /route/v1, /trip/v1, and OSRM's other services on any host, OSRM client libraries, Leaflet Routing Machine, and code that turns OSRM maneuvers into text. List each with what it does and the Mapricot endpoint that replaces it, and tell me about any that Mapricot can't replace. Wait for my OK before changing code.
2. Use Mapricot's client for this project's language if the docs list one; otherwise use plain HTTP. For server code, ask me to create a server key at https://app.mapricot.com/ and put it in MAPRICOT_KEY, wherever this project keeps secrets. Don't ask me to paste it here. Web pages need a browser key: create one with the create_key tool if you have Mapricot's MCP server, or ask me to.
3. Replace each call as the guide shows. OSRM takes and returns coordinates as lon,lat, and Mapricot takes and returns lat and lon by name. Mapricot rejects unknown parameters with a 400, so drop OSRM parameters that have no equivalent.
4. Credit the data wherever the project shows a route, as https://mapricot.com/docs/attribution/ explains.
5. Run the tests, and make one real request to each endpoint you changed. Then remove OSRM's packages and settings, and tell me what changed and what's left, including any OSRM server we no longer need.

The rest of this guide is what the agent works from, and what to check its changes against.

Endpoints

OSRM Mapricot
GET /route/v1/{profile}/{coordinates} POST /routing/v1/route
GET /trip/v1/{profile}/{coordinates} POST /routing/v1/optimize
None POST /routing/v1/isochrone, for the area reachable in a travel time

OSRM servers usually take no key. Mapricot takes one in a header, Authorization: Bearer mapricot_sk_…. In a web page, use a browser key, which works only from the origins you allow.

Routes

OSRM puts the profile and coordinates in the URL. Mapricot takes a JSON body:

OSRM
curl "https://router.project-osrm.org/route/v1/driving/7.4275,43.7396;7.4222,43.734?steps=true"
Mapricot
curl https://api.mapricot.com/routing/v1/route \
  -H "Authorization: Bearer $MAPRICOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"waypoints": [{"lat": 43.7396, "lon": 7.4275}, {"lat": 43.734, "lon": 7.4222}], "mode": "drive", "steps": true}'
OSRM Mapricot
{lon},{lat};… in the path waypoints, 2 to 20 {"lat", "lon"} objects
Profile driving or car "mode": "drive"
Profile cycling or bike "mode": "bicycle"
Profile walking or foot "mode": "walk"
geometries: polyline, polyline6, or geojson geometries, with the same values
steps=true "steps": true
overview=full The default: Mapricot's line is always the full route
exclude=toll, motorway, or ferry, where the server's profile supports it "costing": {"useTolls": 0}, {"useHighways": 0}, or {"useFerry": 0}
alternatives, annotations, bearings, radiuses, hints, approaches, continue_straight, waypoints, snapping None

An OSRM server routes for the profile it was built with, so the profile in the URL often doesn't matter. Mapricot routes for all three modes from one endpoint, and costing adjusts each one, such as a walking speed or a bicycle type: Costing options lists them. A use option of 0 is a strong preference rather than a rule, so a route still takes a toll road, highway, or ferry when there's no other way.

OSRM response Mapricot response
code: "Ok" HTTP 200
400 with code: "NoRoute" 200 with {"routes": []}, not billed
routes[].distance, .duration, with decimals routes[].distanceMeters, .durationSeconds, whole numbers
routes[].geometry routes[].polyline, or routes[].geometry with "geometries": "geojson"
routes[].legs[].distance, .duration legs[].distanceMeters, .durationSeconds
legs[].steps[].maneuver.type and .modifier, such as turn and right steps[].instruction, such as "Turn right onto Route de la Piscine."
steps[].name Part of steps[].instruction
steps[].maneuver.location, as [lon, lat] steps[].lat, steps[].lon
steps[].distance, .duration steps[].distanceMeters, .durationSeconds
waypoints[], snapped to the road, with hint None

OSRM's steps describe each maneuver as a type and a direction, and apps turn them into text with a library such as osrm-text-instructions. Mapricot's steps carry the sentence, in any of 31 languages with lang, so that library can go.

If you use Leaflet Routing Machine with OSRM, Leaflet geocoding and routing gives it a router that calls Mapricot instead.

Trips

OSRM trip Mapricot optimize
source=first&destination=last&roundtrip=false The default: the first and last waypoints stay in place
roundtrip=true, the default Repeat the first waypoint as the last
source=any or destination=any None: choose the start and end yourself
trips[] routes[], with one route
waypoints[].waypoint_index, each input's place in the trip waypointOrder, the input indexes in visiting order

To turn Mapricot's waypointOrder into OSRM's waypoint_index for each input, invert it: the input at waypointOrder[i] has index i. optimize takes the same body as a route, including steps and geometries, and every pair of stops must be within 400 km for driving, or 200 km for walking and cycling.

What has no equivalent

Keep these on OSRM, or replace them with something else:

  • The table service, for travel times between many points.
  • The match service, for snapping GPS traces to roads.
  • The nearest service, and the tile service's debug tiles.
  • Alternative routes and per-segment annotations, such as speeds.
  • Custom profiles built with your own Lua rules.