Migrate from Geoapify to Mapricot
This guide moves an app's Geoapify API calls to Mapricot. It lists the Mapricot endpoint for each Geoapify API, how each parameter and response field carries over, and what has no equivalent. To weigh up the switch first, see Mapricot vs Geoapify.
Mapricot's API isn't compatible with Geoapify's, so each call changes. Both are built on open data, so results are similar, and many field names are close. The main differences are Geoapify's filter and bias strings, which put longitude first, and its GeoJSON responses.
Migrate with a coding agent
Paste this prompt into Claude Code, Cursor, Codex, or another coding agent, in your project. It finds your Geoapify calls, plans the switch with you, and makes it.
Migrate this project from Geoapify to Mapricot, a location API. https://mapricot.com/guides/migrate-from-geoapify/ maps each Geoapify endpoint, parameter, and response field to Mapricot's, and https://mapricot.com/llms.txt lists Mapricot's docs.
1. Find every use of Geoapify in this project: requests to api.geoapify.com and maps.geoapify.com, Geoapify packages such as its geocoder autocomplete, and maps using Geoapify's tiles. 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. Geoapify's bias and filter strings put longitude first, and Mapricot takes lat and lon by name. Mapricot rejects unknown parameters with a 400, so drop Geoapify parameters that have no equivalent.
4. Point maps at 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 Geoapify'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
| Geoapify | Mapricot |
|---|---|
GET /v1/geocode/search |
GET /geocoding/v1/search |
GET /v1/geocode/reverse |
GET /geocoding/v1/reverse |
GET /v1/geocode/autocomplete |
GET /geocoding/v1/autocomplete |
Batch geocoding, POST /v1/batch/geocode/search and polling for the result |
POST /geocoding/v1/search/batch, up to 100 searches answered in the same request |
GET /v2/places |
GET /places/v1/nearby |
GET /v2/place-details |
GET /places/v1/{id}, for a Mapricot ID |
GET /v1/routing |
POST /routing/v1/route |
GET /v1/routing with optimize_stops=true |
POST /routing/v1/optimize |
GET /v1/isoline |
POST /routing/v1/isochrone |
GET /v1/ipinfo |
GET /ip-geolocation/v1/{ip} |
maps.geoapify.com/v1/styles/{style}/style.json |
/tiles/v1/styles/{style}.json |
Geoapify takes its key as apiKey in the URL. Mapricot takes its key in a header, Authorization: Bearer mapricot_sk_…, except for map styles, which take it as ?key=. Geoapify place_id values don't work with Mapricot, so search again for any place you saved by its Geoapify ID.
Geocoding
| Geoapify | Mapricot |
|---|---|
text |
q |
housenumber and street |
address, the house number and street together |
city |
locality |
state |
region |
postcode |
postalCode |
country, a name |
country, a two-letter code |
filter=countrycode:us,ca |
country=us,ca, up to 10 codes |
bias=proximity:-122.68,45.52 |
focus=45.52,-122.68, in lat,lon order |
limit |
limit, up to 20 |
lang |
lang |
Reverse: lat, lon |
Reverse: lat, lon |
type, format, other filter and bias shapes, such as circle: and rect: |
None. Filter on each result's type instead of type |
Results
Geoapify returns GeoJSON by default, or a results list with format=json. Mapricot returns a results list with the address in its own object:
Geoapify features[].properties or results[] |
Mapricot results[] |
|---|---|
lat, lon |
lat, lon |
formatted |
label |
address_line1 |
name |
place_id |
id |
result_type, such as building, street, city, or amenity |
type, such as address, street, locality, or venue |
housenumber |
address.houseNumber |
street |
address.street |
city |
address.locality |
state, state_code |
address.region, address.regionCode |
postcode |
address.postalCode |
country, country_code, such as us |
address.country, address.countryCode, such as US |
distance |
distanceMeters, on reverse and nearby results |
datasource |
source, and attribution for the whole response |
rank, timezone, bbox |
None |
Autocomplete
| Geoapify | Mapricot |
|---|---|
text |
q |
bias=proximity:lon,lat |
focus=lat,lon |
filter=countrycode:us |
country=us |
limit |
limit |
lang |
lang |
type, format |
None |
Results have the same fields as search. If you use @geoapify/geocoder-autocomplete, the address autocomplete guide builds the same kind of form on Mapricot.
Places
| Geoapify Places | Mapricot nearby |
|---|---|
filter=circle:-122.68,45.52,1000 |
lat=45.52&lon=-122.68&radius=1000, with the radius in meters, up to 50,000 |
bias=proximity:lon,lat |
lat, lon. Results come nearest first |
categories=catering.cafe |
category=food:cafe, from Mapricot's categories |
limit |
limit, up to 20 |
lang |
lang |
conditions, name, offset, filter=rect: or place: |
None |
Mapricot's categories are broader than Geoapify's: Geoapify's catering.restaurant is food:restaurant, accommodation.hotel is accommodation, and catering.cafe is food:cafe. Mapricot results have distanceMeters, categories when you send category, and, where the source has them, phones, websites, brand, and openingHours in OpenStreetMap's format.
Routes
Geoapify takes the stops in the URL. Mapricot takes a JSON body:
curl "https://api.geoapify.com/v1/routing?waypoints=43.7396,7.4275|43.734,7.4222&mode=walk&apiKey=…"
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"}'
| Geoapify | Mapricot |
|---|---|
waypoints=lat,lon|lat,lon |
waypoints, 2 to 20 {"lat", "lon"} objects |
mode=drive |
"mode": "drive" |
mode=bicycle |
"mode": "bicycle" |
mode=road_bike or mountain_bike |
"mode": "bicycle" with "costing": {"bicycleType": "road"} or "mountain" |
mode=walk |
"mode": "walk" |
avoid=tolls |
"costing": {"useTolls": 0} |
avoid=highways |
"costing": {"useHighways": 0} |
avoid=ferries |
"costing": {"useFerry": 0} |
route_type=short |
"costing": {"shortest": true} |
max_speed |
costing.topSpeed |
details=instruction_details |
"steps": true |
lang |
lang |
units=imperial |
None: distances are always meters |
Truck, bus, scooter, motorcycle, and transit modes, traffic, format, avoid=location: |
None |
| Geoapify response | Mapricot response |
|---|---|
features[0].properties.distance |
routes[0].distanceMeters |
features[0].properties.time |
routes[0].durationSeconds |
features[0].geometry, a GeoJSON MultiLineString with one line per leg |
routes[0].polyline, or a GeoJSON LineString in geometry with "geometries": "geojson" |
properties.legs[].distance, .time |
legs[].distanceMeters, .durationSeconds |
properties.legs[].steps[].instruction.text |
legs[].steps[].instruction |
Geoapify'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. optimize_stops=true keeps the first and last stops fixed, as Mapricot's optimize does. Mapricot returns the visiting order as waypointOrder, the indexes of your waypoints from 0.
Isolines
| Geoapify | Mapricot |
|---|---|
lat, lon |
"location": {"lat": …, "lon": …} |
mode |
mode: drive, bicycle, or walk |
type=time&range=300,600, in seconds |
"minutes": [5, 10], up to 4, each up to 60 |
type=distance |
None |
avoid |
costing, as for routes |
Both return a GeoJSON FeatureCollection. Each Mapricot feature has its time in properties.minutes, and the largest area comes first. Geoapify's id, which fetches an isoline again, has no equivalent, so store the response if you need it later.
IP geolocation
Without ip, Geoapify's ipinfo looks up the caller. Mapricot always takes the address in the path, GET /ip-geolocation/v1/{ip}, so a server looks up its visitor's IP.
| Geoapify | Mapricot |
|---|---|
country.iso_code, country.name |
countryCode, countryName |
state.name |
regionName |
city.name |
city |
continent.code |
continentCode |
location.latitude, .longitude |
location.lat, .lon |
country.currency, .languages, .flag, postal.code |
None |
When the address has no known location, Mapricot returns "found": false, rather than an error.
Maps
Both serve MapLibre styles, so a map changes only its style URL. Replace https://maps.geoapify.com/v1/styles/osm-bright/style.json?apiKey=… with https://api.mapricot.com/tiles/v1/styles/default.json?key=mapricot_pk_…, or another of Mapricot's styles. Mapricot's tiles are free, but take a browser key with the Map tiles product. Raster tile URLs and Geoapify's static map API have no equivalent.
What has no equivalent
Keep these on Geoapify, or replace them with something else:
- The Route Matrix, Route Planner, and Map Matching APIs.
- Truck, bus, and motorcycle routing, and approximated traffic.
- Boundaries, Postcode, and static map APIs, and raster tiles.
- Place search by name within Places, and the
conditionsfilters.