Migrate from Mapbox to Mapricot
This guide moves an app's Mapbox API calls to Mapricot. It lists the Mapricot endpoint for each Mapbox API, how each parameter and response field carries over, and what has no equivalent. To weigh up the switch first, see Mapricot vs Mapbox.
Mapricot's API isn't compatible with Mapbox's, so each call changes. Most changes are mechanical: renamed parameters, coordinates in lat,lon order rather than lon,lat, and a flatter response.
Migrate with a coding agent
Paste this prompt into Claude Code, Cursor, Codex, or another coding agent, in your project. It finds your Mapbox calls, plans the switch with you, and makes it.
Migrate this project from Mapbox's APIs to Mapricot, a location API. https://mapricot.com/guides/migrate-from-mapbox/ maps each Mapbox endpoint, parameter, and response field to Mapricot's, and https://mapricot.com/llms.txt lists Mapricot's docs.
1. Find every use of Mapbox in this project: requests to api.mapbox.com, Mapbox SDKs and packages, Mapbox GL JS maps, and mapbox:// URLs. 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. Watch for coordinate order: Mapbox uses lon,lat, and Mapricot takes and returns lat and lon by name. Mapricot rejects unknown parameters with a 400, so drop Mapbox parameters that have no equivalent.
4. Move maps from Mapbox GL JS to MapLibre GL JS, as https://mapricot.com/guides/mapbox-to-maplibre/ shows.
5. Credit the data wherever the project shows Mapricot's results, as https://mapricot.com/docs/attribution/ explains.
6. Run the tests, and make one real request to each endpoint you changed. Then remove Mapbox's packages, tokens, 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
| Mapbox | Mapricot |
|---|---|
Geocoding v6 GET /search/geocode/v6/forward |
GET /geocoding/v1/search |
Geocoding v6 GET /search/geocode/v6/reverse |
GET /geocoding/v1/reverse |
Geocoding v6 POST /search/geocode/v6/batch |
POST /geocoding/v1/search/batch, up to 100 searches rather than 1,000 |
Search Box GET /search/searchbox/v1/suggest, then /retrieve/{id} |
GET /geocoding/v1/autocomplete, with no second call |
Search Box GET /search/searchbox/v1/category/{category} |
GET /places/v1/nearby with category |
Search Box GET /search/searchbox/v1/retrieve/{id} |
GET /places/v1/{id}, for a Mapricot ID |
Directions GET /directions/v5/mapbox/{profile}/{coordinates} |
POST /routing/v1/route |
Optimization v1 GET /optimized-trips/v1/mapbox/{profile}/{coordinates} |
POST /routing/v1/optimize |
Isochrone GET /isochrone/v1/mapbox/{profile}/{coordinates} |
POST /routing/v1/isochrone |
Mapbox GL JS with mapbox:// styles |
MapLibre GL JS with Mapricot's styles |
Mapbox takes its token as access_token in the URL. Mapricot takes its key in a header, Authorization: Bearer mapricot_sk_…, except for map styles, which take it as ?key=. Mapbox IDs, such as mapbox_id, don't work with Mapricot, so search again for any place you saved by its Mapbox ID.
Geocoding
| Mapbox | Mapricot |
|---|---|
q |
q |
proximity=-122.68,45.52 |
focus=45.52,-122.68, in lat,lon order. For proximity=ip, find the location with IP geolocation first |
country=us,ca |
country=us,ca, up to 10 codes |
limit, up to 10 |
limit, up to 20 |
language=fr |
lang=fr, one language |
address_line1, or address_number and street |
address |
place |
locality |
district |
county |
region |
region |
postcode |
postalCode |
Reverse: longitude, latitude |
Reverse: lat, lon |
permanent=true |
Not needed: every result can be stored |
bbox, types, worldview, autocomplete, format, entrances |
None. Drop them, and filter on each result's type instead of types |
Mapbox's batch endpoint takes a JSON array of queries. Mapricot's takes {"queries": […]}, each with the same parameters as search, and answers in responses in the same order.
Results
Mapbox returns a GeoJSON FeatureCollection, and Mapricot a results list with the fields at the top level:
Mapbox features[] |
Mapricot results[] |
|---|---|
geometry.coordinates, as [lon, lat] |
lon and lat |
properties.full_address |
label |
properties.name |
name |
properties.feature_type |
type, such as address, street, locality, or venue |
properties.mapbox_id |
id |
properties.context.address.address_number |
address.houseNumber |
properties.context.street.name |
address.street |
properties.context.postcode.name |
address.postalCode |
properties.context.place.name |
address.locality |
properties.context.region.name, .region_code |
address.region, address.regionCode |
properties.context.country.name, .country_code |
address.country, address.countryCode, in capitals |
| Reverse: no distance | Reverse: distanceMeters |
attribution, a string |
attribution, a list of sources to credit |
Fields a source doesn't have are left out, not empty.
Autocomplete
Search Box suggestions have no coordinates, so Mapbox apps call /retrieve/{id} when someone picks one, and group the calls with a session_token. Mapricot's autocomplete results have lat, lon, and the address already, so delete the retrieve step and the session token.
Search Box suggest |
Mapricot autocomplete |
|---|---|
q |
q |
proximity |
focus, in lat,lon order |
country |
country |
limit |
limit |
language |
lang |
session_token, types, poi_category, bbox, navigation_profile, origin, eta_type |
None |
The address autocomplete guide builds a form on it.
Category search
Search Box category/{category} |
Mapricot nearby |
|---|---|
{category} in the path, such as coffee |
category=food:coffee_shop, from Mapricot's categories |
proximity=-122.68,45.52 |
lat=45.52&lon=-122.68, which is required |
limit |
limit, up to 20 |
language |
lang |
bbox, country, poi_category_exclusions |
None. Use radius, in meters, to keep results close |
Mapricot's categories are broader than Mapbox's: Mapbox's restaurant is food:restaurant, and hotel is accommodation. Results come nearest first, with distanceMeters.
Directions
Mapbox puts the profile and coordinates in the URL. Mapricot takes a JSON body:
curl "https://api.mapbox.com/directions/v5/mapbox/walking/7.4275,43.7396;7.4222,43.734?steps=true&access_token=pk.…"
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": "walk", "steps": true}'
| Mapbox | Mapricot |
|---|---|
Profile driving or driving-traffic |
"mode": "drive", without traffic |
Profile cycling |
"mode": "bicycle" |
Profile walking |
"mode": "walk" |
{lon},{lat};…, 2 to 25 points |
waypoints, 2 to 20 {"lat", "lon"} objects |
geometries: polyline, polyline6, or geojson |
geometries, with the same values |
steps=true |
"steps": true |
language |
lang |
exclude=toll,motorway,ferry |
"costing": {"useTolls": 0, "useHighways": 0, "useFerry": 0}, which avoids them where there's another way |
max_height, max_width, max_weight |
costing.height, .width, .weight |
walking_speed, in meters per second |
costing.walkingSpeed, in km/h: multiply by 3.6 |
alternatives, annotations, overview, bearings, radiuses, approaches, depart_at, arrive_by, banner_instructions, voice_instructions |
None |
| Mapbox response | Mapricot response |
|---|---|
code: "Ok" |
HTTP 200 |
code: "NoRoute" |
{"routes": []}, not billed |
routes[].distance, .duration |
routes[].distanceMeters, .durationSeconds, as whole numbers |
routes[].geometry |
routes[].polyline, or routes[].geometry with "geometries": "geojson" |
legs[].distance, .duration |
legs[].distanceMeters, .durationSeconds |
steps[].maneuver.instruction |
steps[].instruction |
steps[].maneuver.location, as [lon, lat] |
steps[].lat, steps[].lon |
steps[].distance, .duration |
steps[].distanceMeters, .durationSeconds |
waypoints[], snapped to the road |
None |
Optimization
Mapbox's Optimization v1 chooses its own start and end unless you set source=first and destination=last, and returns to the start unless you set roundtrip=false. Mapricot's optimize always keeps the first and last waypoints in place, so:
- For
source=first&destination=last&roundtrip=false, send the stops as they are. - For a round trip, repeat the first stop as the last waypoint.
It takes the same body as a route. Where Mapbox returns trips[] and each waypoint's waypoint_index, Mapricot returns one route in routes with waypointOrder, the indexes of your waypoints in visiting order. Mapricot takes up to 20 stops, where Mapbox takes 12, and has no distributions for pickups and drop-offs.
Isochrones
| Mapbox | Mapricot |
|---|---|
| Profile in the path | mode |
{lon},{lat} in the path |
"location": {"lat": …, "lon": …} |
contours_minutes=5,10,15 |
"minutes": [5, 10, 15], up to 4, each up to 60 |
polygons=true |
Not needed: areas are always polygons |
generalize, in meters |
generalize, in meters, from 10 to 5,000 |
contours_meters, contours_colors, denoise, exclude, depart_at |
None |
Both return a GeoJSON FeatureCollection. Each Mapricot feature has its time in properties.minutes, where Mapbox has properties.contour, and the largest area comes first.
Maps
Mapricot's map tiles work with MapLibre GL JS, the open-source fork of Mapbox GL JS, and most map code carries over with new imports, a style URL, and renamed CSS classes. Migrate from Mapbox GL JS to MapLibre walks through it, including the geocoder control. On iOS and Android, use MapLibre Native in place of the Mapbox Maps SDK, or MapLibre React Native.
What has no equivalent
Keep these on Mapbox, or replace them with something else:
- Live and predicted traffic: the
driving-trafficprofile,depart_at, andarrive_by. - The Matrix, Map Matching, Static Images, and Tilequery APIs, and Optimization v2.
- Mapbox Studio styles and Mapbox's satellite and terrain tiles.
- The Navigation SDKs.