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.

Prompt
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.