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.

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

Geoapify
curl "https://api.geoapify.com/v1/routing?waypoints=43.7396,7.4275|43.734,7.4222&mode=walk&apiKey=…"
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"}'
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 conditions filters.