Migrate from Geocode Earth to Mapricot

This guide moves an app's Geocode Earth API calls to Mapricot. It lists the Mapricot endpoint for each Geocode Earth endpoint, how each parameter and response field carries over, and what has no equivalent. To weigh up the switch first, see Mapricot vs Geocode Earth.

Mapricot's API isn't compatible with Geocode Earth's, so each call changes, but the changes are small. Both search the same open datasets, the parameters do the same jobs under shorter names, and the response is a flat results list rather than GeoJSON.

Migrate with a coding agent

Paste this prompt into Claude Code, Cursor, Codex, or another coding agent, in your project. It finds your Geocode Earth calls, plans the switch with you, and makes it.

Prompt
Migrate this project from Geocode Earth to Mapricot, a location API. https://mapricot.com/guides/migrate-from-geocode-earth/ maps each Geocode Earth endpoint, parameter, and response field to Mapricot's, and https://mapricot.com/llms.txt lists Mapricot's docs.

1. Find every use of Geocode Earth in this project: requests to api.geocode.earth, Pelias client libraries pointed at it, and Geocode Earth's autocomplete element. 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. Geocode Earth returns GeoJSON with [lon, lat] coordinates, and Mapricot returns lat and lon by name. Mapricot rejects unknown parameters with a 400, so drop Geocode Earth parameters that have no equivalent.
4. Credit the data wherever the project shows Mapricot's results, as https://mapricot.com/docs/attribution/ explains.
5. Run the tests, and make one real request to each endpoint you changed. Then remove Geocode Earth'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

Geocode Earth Mapricot
GET /v1/search GET /geocoding/v1/search
GET /v1/search/structured GET /geocoding/v1/search, with the address in parts
GET /v1/autocomplete GET /geocoding/v1/autocomplete
GET /v1/reverse GET /geocoding/v1/reverse
GET /v1/place?ids= GET /places/v1/{id}, one Mapricot ID at a time
A loop of searches over a file POST /geocoding/v1/search/batch, up to 100 searches a request

Geocode Earth takes its key as api_key in the URL. Mapricot takes its key in a header, Authorization: Bearer mapricot_sk_…. Geocode Earth's gid values don't work with Mapricot's place lookup, so search again for any place you saved by its gid.

Search and autocomplete

Geocode Earth 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, up to 40 limit, up to 20
lang lang
boundary.rect.*, boundary.circle.*, boundary.gid, layers, sources None. Filter on each result's type instead of layers

Autocomplete takes the same parameters as search: q, focus, country, limit, and lang. Geocode Earth's autocomplete element has no Mapricot equivalent; the address autocomplete guide builds a form that does the same job.

Geocode Earth search/structured Mapricot search
address address
locality locality
county county
region region
postalcode postalCode
country, a name or code country, two-letter codes
neighbourhood, borough None. Put them in address or leave them out

Mapricot takes the parts on the same search endpoint, in place of q, and ignores parts sent blank.

Reverse

Geocode Earth Mapricot
point.lat, point.lon lat, lon
size limit
lang lang
layers, sources, boundary.circle.radius, boundary.country None

Results

Geocode Earth 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.source source
properties.housenumber address.houseNumber
properties.street address.street
properties.postalcode address.postalCode
properties.locality address.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.addendum.osm.phone, .website phones, websites
properties.confidence, .match_type, .accuracy, and the *_gid fields None
geocoding.attribution, a URL attribution, a list of the sources in the results, to credit

Fields a source doesn't have are left out, not empty. When nothing matches, both return an empty list.

What has no equivalent

Keep these on Geocode Earth, or replace them with something else:

  • The Geometry API, for boundary polygons.
  • Bounding box and circle filters, and filtering by layer or source.
  • Looking up several places in one request.