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.

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

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:

Mapbox
curl "https://api.mapbox.com/directions/v5/mapbox/walking/7.4275,43.7396;7.4222,43.734?steps=true&access_token=pk.…"
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": "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-traffic profile, depart_at, and arrive_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.