Migrate from the Google Maps APIs to Mapricot
This guide moves an app's Google Maps Platform calls to Mapricot. It lists the Mapricot endpoint for each Google API, how each parameter and response field carries over, and what has no equivalent. To weigh up the switch first, see Mapricot vs Google Maps.
Mapricot's API isn't compatible with Google's, so each call changes. Coordinates keep Google's latitude-first order, but lng becomes lon, and responses are flatter, with no status field.
Migrate with a coding agent
Paste this prompt into Claude Code, Cursor, Codex, or another coding agent, in your project. It finds your Google Maps calls, plans the switch with you, and makes it.
Migrate this project from the Google Maps Platform APIs to Mapricot, a location API. https://mapricot.com/guides/migrate-from-google-maps/ maps each Google endpoint, parameter, and response field to Mapricot's, and https://mapricot.com/llms.txt lists Mapricot's docs.
1. Find every use of Google Maps Platform in this project: requests to maps.googleapis.com, places.googleapis.com, and routes.googleapis.com, Google Maps client libraries, and the Maps JavaScript API with its markers and Places widgets. 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. Google's lng is Mapricot's lon. Mapricot reports errors with HTTP status codes rather than a status field, and rejects unknown parameters with a 400, so drop Google parameters that have no equivalent.
4. Move maps from the Maps JavaScript API to MapLibre GL JS with Mapricot's map tiles, 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 Google'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
| Mapricot | |
|---|---|
Geocoding GET /maps/api/geocode/json?address= |
GET /geocoding/v1/search |
Geocoding GET /maps/api/geocode/json?latlng= |
GET /geocoding/v1/reverse |
Places Autocomplete POST /v1/places:autocomplete, then Place Details |
GET /geocoding/v1/autocomplete, with no second call |
Places Text Search POST /v1/places:searchText |
GET /geocoding/v1/search |
Places Nearby Search POST /v1/places:searchNearby |
GET /places/v1/nearby |
Place Details GET /v1/places/{id} |
GET /places/v1/{id}, for a Mapricot ID |
Routes POST /directions/v2:computeRoutes |
POST /routing/v1/route |
Directions (Legacy) GET /maps/api/directions/json |
POST /routing/v1/route |
| Either, with waypoint optimization | POST /routing/v1/optimize |
Geolocation POST /geolocation/v1/geolocate |
GET /ip-geolocation/v1/{ip}, from an IP address only |
| Maps JavaScript API | MapLibre GL JS with Mapricot's map tiles |
Google takes its key as key in the URL or an X-Goog-Api-Key header. Mapricot takes its key in a header, Authorization: Bearer mapricot_sk_…, except for map styles, which take it as ?key=. Mapricot has no field masks, so drop X-Goog-FieldMask: each response has every field.
Google place IDs don't work with Mapricot, so search again for any place you saved by its Google ID. Mapricot's results can be stored and cached for as long as you like, and shown on any map.
Geocoding
| Mapricot | |
|---|---|
address |
q |
components=country:US |
country=us, up to 10 codes |
Other components, such as postal_code or locality |
None as filters. To send an address you already have in parts, use address, locality, region, and postalCode in place of q |
bounds, region |
focus=lat,lon, which ranks results near a point higher, or country to keep them in a country |
language |
lang |
Reverse: latlng=45.52,-122.68 |
Reverse: lat=45.52&lon=-122.68 |
result_type, location_type, extra_computations |
None. Filter on each result's type |
Results
Google results[] |
Mapricot results[] |
|---|---|
status: "OK" |
HTTP 200 |
status: "ZERO_RESULTS" |
HTTP 200 with an empty results list |
formatted_address |
label |
geometry.location.lat, .lng |
lat, lon |
place_id |
id |
types |
type, such as address, street, locality, or venue |
geometry.location_type: "ROOFTOP" |
type: "address"; a broader match has another type |
address_components with type street_number |
address.houseNumber |
address_components with type route |
address.street |
address_components with type locality |
address.locality |
address_components with type administrative_area_level_1: long_name, short_name |
address.region, address.regionCode |
address_components with type postal_code |
address.postalCode |
address_components with type country: long_name, short_name |
address.country, address.countryCode |
partial_match, plus_code, geometry.viewport |
None |
| Reverse: no distance | Reverse: distanceMeters |
Mapricot's address is an object with named fields, so code that loops over address_components looking for a type becomes a field read. Fields a source doesn't have are left out, not empty.
Autocomplete
Google's autocomplete predictions have no coordinates, so apps call Place Details when someone picks one, and group the calls with a sessionToken. Mapricot's autocomplete results have lat, lon, and the address already, so delete the details call and the session token.
| Places Autocomplete | Mapricot autocomplete |
|---|---|
input |
q |
locationBias |
focus=lat,lon, the center of the circle |
includedRegionCodes |
country, up to 10 codes |
languageCode |
lang |
sessionToken, includedPrimaryTypes, locationRestriction, origin, includeQueryPredictions |
None |
suggestions[].placePrediction.text.text |
results[].label |
suggestions[].placePrediction.structuredFormat.mainText.text |
results[].name |
suggestions[].placePrediction.placeId |
results[].id |
The legacy GET /maps/api/place/autocomplete/json maps the same way: input to q, location to focus, and components=country:us to country=us. Mapricot has no ready-made widget like PlaceAutocompleteElement. The address autocomplete guide builds a form that does the same job in a few dozen lines.
Nearby search
| Places Nearby Search | Mapricot nearby |
|---|---|
locationRestriction.circle.center.latitude, .longitude |
lat, lon |
locationRestriction.circle.radius |
radius, in meters, up to 50,000 |
includedTypes |
category, from Mapricot's categories |
maxResultCount |
limit, up to 20 |
languageCode |
lang |
rankPreference: "DISTANCE" |
The default: results come nearest first |
excludedTypes, includedPrimaryTypes, regionCode |
None |
Mapricot's categories are broader than Google's place types: Google's cafe is food:cafe, restaurant is food:restaurant, lodging is accommodation, and bank is finance.
Google places[] |
Mapricot results[] |
|---|---|
id |
id |
displayName.text |
name |
formattedAddress |
label |
location.latitude, .longitude |
lat, lon |
types |
categories, when you send category |
nationalPhoneNumber, internationalPhoneNumber |
phones, as the source wrote them |
websiteUri |
websites |
regularOpeningHours |
openingHours, in OpenStreetMap's format, where known |
rating, reviews, photos, priceLevel |
None |
Text Search maps to Mapricot's search: textQuery to q, locationBias to focus, and pageSize to limit. To find a kind of place, such as "coffee near me", use nearby with a category instead, since search matches names.
Routes
The Routes API and the legacy Directions API both map to one Mapricot endpoint:
| Routes API | Directions (Legacy) | Mapricot |
|---|---|---|
origin, intermediates, destination, each with location.latLng |
origin, waypoints, destination |
waypoints, 2 to 20 {"lat", "lon"} objects, in order |
travelMode: "DRIVE" |
mode=driving |
"mode": "drive" |
travelMode: "BICYCLE" |
mode=bicycling |
"mode": "bicycle" |
travelMode: "WALK" |
mode=walking |
"mode": "walk" |
routeModifiers.avoidTolls |
avoid=tolls |
"costing": {"useTolls": 0} |
routeModifiers.avoidHighways |
avoid=highways |
"costing": {"useHighways": 0} |
routeModifiers.avoidFerries |
avoid=ferries |
"costing": {"useFerry": 0} |
optimizeWaypointOrder: true |
waypoints=optimize:true|… |
POST /routing/v1/optimize |
languageCode |
language |
lang |
polylineEncoding: "GEO_JSON_LINESTRING" |
None | "geometries": "geojson" |
TRANSIT, TWO_WHEELER, routingPreference, departureTime, computeAlternativeRoutes, units |
transit, departure_time, alternatives, units |
None |
Google's avoid options rule roads out where Mapricot's costing steers away from them, so a Mapricot route still takes a toll road when there's no other way. Mapricot returns turn-by-turn steps only when you send "steps": true.
| Routes API response | Directions (Legacy) response | Mapricot response |
|---|---|---|
routes[].distanceMeters |
routes[].legs[].distance.value, per leg |
routes[].distanceMeters, and per leg |
routes[].duration, such as "739s" |
routes[].legs[].duration.value |
routes[].durationSeconds, a number |
routes[].polyline.encodedPolyline |
routes[].overview_polyline.points |
routes[].polyline, the same encoding |
legs[].steps[].navigationInstruction.instructions |
legs[].steps[].html_instructions |
legs[].steps[].instruction, plain text |
optimizedIntermediateWaypointIndex |
waypoint_order |
waypointOrder |
| No route: an empty response | status: "ZERO_RESULTS" |
{"routes": []}, not billed |
Mapricot's polyline uses Google's encoding with five decimal places, so a decoder you already use keeps working. Google's optimized order lists only the intermediate waypoints, counted from 0. Mapricot's waypointOrder lists every waypoint, so the origin is 0 and the destination is last: subtract 1 from the middle values to get Google's.
IP geolocation
Google's Geolocation API locates the device sending the request, from cell towers and Wi-Fi, falling back to its IP address. Mapricot's looks up any IP address you give it, so a server finds a visitor's location from the visitor's IP: GET /ip-geolocation/v1/{ip}. Google's location.lat and .lng become location.lat and .lon. Mapricot gives no accuracy, since an IP address locates a network, not a device. For a precise position in a browser, use the browser's own Geolocation API.
Maps
The Maps JavaScript API has no drop-in replacement, so map code is rewritten for MapLibre GL JS, which draws Mapricot's free map tiles. The concepts carry over: google.maps.Map is maplibregl.Map, AdvancedMarkerElement is maplibregl.Marker, and InfoWindow is maplibregl.Popup. Two differences catch people out: MapLibre takes coordinates as [lng, lat] arrays, and zoom levels are one lower for the same view. MapLibre markers and popups and MapLibre routes show the pieces most apps need, and MapLibre React replaces @vis.gl/react-google-maps.
What has no equivalent
Keep these on Google, or replace them with something else:
- Live traffic, transit directions, and departure times.
- The Distance Matrix and Route Matrix APIs, Roads, Elevation, Time Zone, and Address Validation.
- Ratings, reviews, photos, and price levels for places.
- Street View, satellite imagery, and the Static Maps API.