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.

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