Migrate from GraphHopper to Mapricot
This guide moves an app's GraphHopper API calls to Mapricot. It lists the Mapricot endpoint for each GraphHopper API, how each parameter and response field carries over, and what has no equivalent. To weigh up the switch first, see Mapricot vs GraphHopper.
Mapricot's API isn't compatible with GraphHopper's, so each call changes. Both route on OpenStreetMap roads, so routes are similar. The main differences are units, since GraphHopper gives times in milliseconds, and coordinates, which Mapricot always takes as named lat and lon.
Migrate with a coding agent
Paste this prompt into Claude Code, Cursor, Codex, or another coding agent, in your project. It finds your GraphHopper calls, plans the switch with you, and makes it.
Migrate this project from GraphHopper's APIs to Mapricot, a location API. https://mapricot.com/guides/migrate-from-graphhopper/ maps each GraphHopper endpoint, parameter, and response field to Mapricot's, and https://mapricot.com/llms.txt lists Mapricot's docs.
1. Find every use of GraphHopper in this project: requests to graphhopper.com/api/1, GraphHopper client libraries, and Leaflet or MapLibre plugins that call it. 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. GraphHopper gives times in milliseconds and Mapricot in seconds, and GraphHopper's POST body takes points as [lon, lat] where Mapricot takes lat and lon by name. Mapricot rejects unknown parameters with a 400, so drop GraphHopper parameters that have no equivalent.
4. Credit the data wherever the project shows Mapricot's results, as https://mapricot.com/docs/attribution/ explains.
5. Run the tests, and make one real request to each endpoint you changed. Then remove GraphHopper's packages, keys, and settings, and tell me what changed and what's left.
The rest of this guide is what the agent works from, and what to check its changes against.
Endpoints
| GraphHopper | Mapricot |
|---|---|
GET or POST /api/1/route |
POST /routing/v1/route |
POST /api/1/vrp, for one vehicle and no constraints |
POST /routing/v1/optimize |
GET /api/1/isochrone |
POST /routing/v1/isochrone |
GET /api/1/geocode?q= |
GET /geocoding/v1/search, or autocomplete as people type |
GET /api/1/geocode?reverse=true |
GET /geocoding/v1/reverse |
GET /api/1/geocode?reverse=true&osm_tag= |
GET /places/v1/nearby with category |
GraphHopper takes its key as key in the URL. Mapricot takes its key in a header, Authorization: Bearer mapricot_sk_….
Routes
| GraphHopper | Mapricot |
|---|---|
GET: point=lat,lng, repeated. POST: points as [lng, lat] pairs |
waypoints, 2 to 20 {"lat", "lon"} objects |
profile=car |
"mode": "drive" |
profile=bike |
"mode": "bicycle" |
profile=racingbike or mtb |
"mode": "bicycle" with "costing": {"bicycleType": "road"} or "mountain" |
profile=foot |
"mode": "walk" |
instructions=true |
"steps": true. GraphHopper includes instructions by default, and Mapricot leaves them out by default |
locale |
lang |
points_encoded=true |
"geometries": "polyline", the default |
points_encoded=false |
"geometries": "geojson" |
A custom model that avoids tolls, such as toll == ALL with multiply_by: 0 |
"costing": {"useTolls": 0} |
| A custom model that avoids motorways or ferries | "costing": {"useHighways": 0} or {"useFerry": 0} |
algorithm=alternative_route, heading, curbside, snap_preventions, details, elevation, custom_model beyond these |
None |
Mapricot's costing steers away from tolls, highways, and ferries rather than ruling them out, so a route still takes a toll road when there's no other way.
| GraphHopper response | Mapricot response |
|---|---|
paths[0].distance, in meters |
routes[0].distanceMeters |
paths[0].time, in milliseconds |
routes[0].durationSeconds, in seconds: divide by 1,000 |
paths[0].points, an encoded polyline |
routes[0].polyline, the same encoding, five decimal places |
paths[0].instructions[].text |
routes[0].legs[].steps[].instruction |
instructions[].distance, .time in milliseconds |
steps[].distanceMeters, .durationSeconds |
instructions[].interval, indexes into the line |
steps[].lat, steps[].lon |
instructions[].sign, a turn code |
None: the instruction is text |
| No legs: one list of instructions for the whole route | legs, one per pair of waypoints, each with its distance, duration, and steps |
No route: 400 with a message |
200 with {"routes": []}, not billed |
Route optimization
GraphHopper's Route Optimization API plans routes for fleets, with vehicles, capacities, and time windows. Mapricot's optimize covers the simplest case: one trip that visits up to 20 stops in the fastest order, from a fixed start to a fixed end. Send the stops as waypoints in a route body, with the vehicle's start first and its end last, repeating the start to come back. The response is a route, with waypointOrder, the indexes of your waypoints in visiting order. Plans with several vehicles, capacities, time windows, or pickups and deliveries have no equivalent.
Isochrones
| GraphHopper | Mapricot |
|---|---|
point=lat,lng |
"location": {"lat": …, "lon": …} |
profile |
mode, as for routes |
time_limit=600, in seconds |
"minutes": [10], up to 4, each up to 60 |
time_limit=900&buckets=3, which splits 15 minutes into three |
"minutes": [5, 10, 15] |
distance_limit, reverse_flow |
None |
GraphHopper returns polygons, each a GeoJSON feature with a bucket number. Mapricot returns a GeoJSON FeatureCollection with one polygon per time, each with its minutes, largest first.
Geocoding
| GraphHopper | Mapricot |
|---|---|
q |
q |
point=lat,lng, to bias |
focus=lat,lon |
locale |
lang |
limit |
limit, up to 20 |
Reverse: reverse=true&point=lat,lng |
Reverse: lat, lon on /geocoding/v1/reverse |
provider |
None: Mapricot has one geocoder |
osm_tag=amenity:cafe, for reverse |
category=food:cafe on nearby search |
GraphHopper hits[] |
Mapricot results[] |
|---|---|
point.lat, .lng |
lat, lon |
name |
name |
housenumber, street, postcode, city, state |
address.houseNumber, .street, .postalCode, .locality, .region |
country, countrycode |
address.country, address.countryCode |
osm_id, osm_type |
id, a Mapricot ID |
osm_key, osm_value |
type, and categories on nearby results |
| No label | label, the whole address on one line |
What has no equivalent
Keep these on GraphHopper, or replace them with something else:
- The Matrix API and Map Matching API.
- Fleet planning in Route Optimization: several vehicles, capacities, time windows, and shifts.
- Truck, scooter, and hiking profiles, elevation data, and custom models beyond avoiding tolls, highways, and ferries.
- Alternative routes and path details.