Migrate from Stadia Maps to Mapricot
This guide moves an app's Stadia Maps API calls to Mapricot. It lists the Mapricot endpoint for each Stadia Maps API, how each parameter and response field carries over, and what has no equivalent. To weigh up the switch first, see Mapricot vs Stadia Maps.
Mapricot's API isn't compatible with Stadia's, so each call changes, but the changes are small. Both are built on the same open data, maps on both use MapLibre, and the routing options do the same jobs under camelCase names.
Migrate with a coding agent
Paste this prompt into Claude Code, Cursor, Codex, or another coding agent, in your project. It finds your Stadia Maps calls, plans the switch with you, and makes it.
Migrate this project from Stadia Maps to Mapricot, a location API. https://mapricot.com/guides/migrate-from-stadia-maps/ maps each Stadia Maps endpoint, parameter, and response field to Mapricot's, and https://mapricot.com/llms.txt lists Mapricot's docs.
1. Find every use of Stadia Maps in this project: requests to api.stadiamaps.com and tiles.stadiamaps.com, the @stadiamaps packages and SDKs, and Stadia map styles. 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. Stadia returns geocoding results as GeoJSON with [lon, lat] coordinates and route lengths in kilometers or miles, and Mapricot returns lat and lon by name and meters. Mapricot rejects unknown parameters with a 400, so drop Stadia parameters that have no equivalent.
4. Point maps at Mapricot's styles, as https://mapricot.com/docs/map-tiles/ 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 Stadia'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
| Stadia Maps | Mapricot |
|---|---|
GET /geocoding/v1/search or /v2/search |
GET /geocoding/v1/search |
GET /geocoding/v1/search/structured |
GET /geocoding/v1/search, with the address in parts |
GET /geocoding/v1/autocomplete or /v2/autocomplete |
GET /geocoding/v1/autocomplete |
GET /geocoding/v1/reverse or /v2/reverse |
GET /geocoding/v1/reverse |
Place lookup, by gid |
GET /places/v1/{id}, for a Mapricot ID |
| Bulk geocoding | POST /geocoding/v1/search/batch, up to 100 searches |
POST /route/v1 |
POST /routing/v1/route |
POST /optimized_route/v1 |
POST /routing/v1/optimize |
POST /isochrone/v1 |
POST /routing/v1/isochrone |
tiles.stadiamaps.com/styles/{style}.json |
/tiles/v1/styles/{style}.json |
Stadia takes its key as api_key in the URL, or lets web pages call from domains you list with no key. Mapricot takes its key in a header, Authorization: Bearer mapricot_sk_…, except for map styles, which take it as ?key=. In a web page, use a browser key, which works only from the origins you allow. Stadia's gid values don't work with Mapricot's place lookup, so search again for any place you saved by its gid.
Geocoding
| Stadia Maps | Mapricot |
|---|---|
text |
q |
focus.point.lat, focus.point.lon |
focus=lat,lon |
boundary.country=US,CA |
country=us,ca, up to 10 two-letter codes |
size |
limit, up to 20 |
lang |
lang |
Structured: address, locality, county, region, postalcode, country |
address, locality, county, region, postalCode, and a two-letter country |
Reverse: point.lat, point.lon |
Reverse: lat, lon |
boundary.rect.*, boundary.circle.*, boundary.gid, layers, sources |
None. Filter on each result's type instead of layers |
Results
Stadia v1 features[] |
Mapricot results[] |
|---|---|
geometry.coordinates, as [lon, lat] |
lon, lat |
properties.label |
label |
properties.name |
name |
properties.gid |
id |
properties.layer |
type, such as address, street, locality, or venue |
properties.housenumber, .street, .postalcode, .locality |
address.houseNumber, .street, .postalCode, .locality |
properties.region, .region_a |
address.region, address.regionCode |
properties.country, .country_code |
address.country, address.countryCode |
properties.distance, in kilometers |
distanceMeters, in meters, on reverse results |
properties.confidence, .match_type, .accuracy |
None |
In v2 responses, formatted_address_line is Mapricot's label, and the fields in address_components are in Mapricot's address.
Routes
Stadia and Mapricot both take routes as a JSON body. The common fields:
Stadia route/v1 |
Mapricot |
|---|---|
locations, each {"lat", "lon"} |
waypoints, 2 to 20 {"lat", "lon"} objects |
costing: "auto" |
"mode": "drive" |
costing: "bicycle" |
"mode": "bicycle" |
costing: "pedestrian" |
"mode": "walk" |
costing_options.auto.use_tolls |
costing.useTolls |
directions_options.language |
lang |
units |
None: distances are always meters |
truck, bus, motor_scooter, and motorcycle costing, date_time, alternates, format: "osrm", exclude_locations |
None |
Stadia's costing options move up one level, into costing, and take camelCase names: costing_options.auto.use_highways is costing.useHighways, bicycle.bicycle_type is costing.bicycleType, and pedestrian.walking_speed is costing.walkingSpeed. Costing options lists every option Mapricot takes; any other gets a 400 that names it. Mapricot returns turn-by-turn steps only when you send "steps": true.
| Stadia response | Mapricot response |
|---|---|
trip.summary.length, in units |
routes[0].distanceMeters, in meters |
trip.summary.time |
routes[0].durationSeconds |
trip.legs[].shape, a polyline with six decimal places, per leg |
routes[0].polyline, five decimal places, for the whole route. Send "geometries": "polyline6" for six |
trip.legs[].summary |
legs[].distanceMeters, .durationSeconds |
trip.legs[].maneuvers[].instruction |
legs[].steps[].instruction |
maneuvers[].length, .time |
steps[].distanceMeters, .durationSeconds |
maneuvers[].begin_shape_index |
steps[].lat, steps[].lon |
No route: an error with error_code |
{"routes": []}, not billed |
Optimized routes
optimized_route/v1 and Mapricot's optimize both keep the first and last locations fixed and reorder the rest. Where Stadia gives each location's original_index in trip.locations, Mapricot returns waypointOrder, the indexes of your waypoints in visiting order. Mapricot takes up to 20 waypoints.
Isochrones
Stadia isochrone/v1 |
Mapricot |
|---|---|
locations, one {"lat", "lon"} |
location, {"lat", "lon"} |
costing |
mode, as for routes, with options in costing |
contours: [{"time": 5}, {"time": 10}] |
"minutes": [5, 10], up to 4, each up to 60 |
contours with distance |
None |
polygons: true |
Not needed: areas are always polygons |
generalize |
generalize, in meters, from 10 to 5,000 |
denoise, show_locations |
None |
Both return a GeoJSON FeatureCollection. Each Mapricot feature has its time in properties.minutes, where Stadia has properties.contour, and the largest area comes first.
Maps
Both serve MapLibre styles, so a map changes only its style URL. Replace https://tiles.stadiamaps.com/styles/alidade_smooth.json with https://api.mapricot.com/tiles/v1/styles/light.json?key=mapricot_pk_…, or another of Mapricot's styles: default, light, dark, bright, grayscale, or outdoors. Mapricot's tiles are free, but take a browser key with the Map tiles product. On iOS and Android, MapLibre Native takes the same style URL with a server key.
What has no equivalent
Keep these on Stadia Maps, or replace them with something else:
- The Time/Distance Matrix, Map Matching, Elevation, and Time Zone APIs.
- Truck, bus, scooter, and motorcycle routing, and traffic-influenced times.
- Raster tiles, static maps, and Stamen styles.