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.
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:
curl "https://router.project-osrm.org/route/v1/driving/7.4275,43.7396;7.4222,43.734?steps=true"
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.