Migrate from Geocodio to Mapricot

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

Mapricot's API isn't compatible with Geocodio's, so each call changes. The main differences are lng, which becomes lon, smaller batches, and the address, which Mapricot keeps as one street field rather than Geocodio's number, directional, street, and suffix.

Migrate with a coding agent

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

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

1. Find every use of Geocodio in this project: requests to api.geocod.io, Geocodio client libraries, and any data appends requested with fields. List each with what it does and the Mapricot endpoint that replaces it, and tell me about any that Mapricot can't replace, such as census or congressional district data. 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. Geocodio's lng is Mapricot's lon, and Mapricot's batches hold up to 100 searches, so split larger ones. Mapricot rejects unknown parameters with a 400, so drop Geocodio 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 Geocodio'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

Geocodio Mapricot
GET /v2.1/geocode GET /geocoding/v1/search
POST /v2.1/geocode, up to 10,000 addresses POST /geocoding/v1/search/batch, up to 100 searches a request
GET /v2.1/reverse GET /geocoding/v1/reverse
POST /v2.1/reverse, a batch One GET /geocoding/v1/reverse per point
GET /v2.1/distance with mode=driving One POST /routing/v1/route per destination
Lists, for spreadsheet uploads The batch geocoding guide, which geocodes a CSV file with a short script

Geocodio takes its key as api_key in the URL. Mapricot takes its key in a header, Authorization: Bearer mapricot_sk_….

Geocoding

Geocodio Mapricot
q q
street, with street2 address, with the unit in the same string
city locality
county county
state_province region
postal_code postalCode
country, a name or code, defaulting to the US country, two-letter codes, up to 10. Without it, Mapricot searches the whole world
limit limit, up to 20
addressee None. Leave the business name out of the address
fields, format, and the distance_* parameters None
Reverse: q=38.9,-77.0 Reverse: lat=38.9&lon=-77.0

Geocodio assumes the US when an address doesn't say otherwise. Mapricot covers the world, so send country=us to keep the same behavior for US addresses that leave out the country.

Geocodio's batch takes a JSON list of addresses, or an object keyed by your own IDs. Mapricot's takes {"queries": […]}, each with the same parameters as search, and answers in responses in the same order, so keep your IDs in a list alongside. A batch of 10,000 becomes 100 batches of 100.

Results

Geocodio results[] Mapricot results[]
formatted_address label
location.lat, .lng lat, lon
accuracy_type: "rooftop" or "range_interpolation" type: "address"
accuracy_type: "street_center" type: "street"
accuracy_type: "place" or "county" type: "locality" or "county"
address_components.number address.houseNumber
address_components.formatted_street address.street
address_components.city address.locality
address_components.state_province address.regionCode, with the name in address.region
address_components.postal_code address.postalCode
address_components.country address.countryCode
source source, and attribution for the whole response
accuracy, a score None. Use type to tell an exact match from a broader one
address_components.county, address_lines, stable_address_key, fields None
Reverse: distance Reverse: distanceMeters

Mapricot gives the street as one string, such as N Highland St, so code that joins Geocodio's predirectional, street, and suffix reads address.street instead.

Distance

Geocodio's Distance API gives the driving distance and time from one origin to many destinations. Mapricot's routing gives them for one route at a time: send a route from the origin to each destination, as waypoints with two points, and read routes[0].distanceMeters and durationSeconds. Each route is one request. Geocodio's distance_miles is Mapricot's meters divided by 1,609.34. Straight-line distances need no API at all.

What has no equivalent

Keep these on Geocodio, or replace them with something else:

  • Data appends: census data, congressional and legislative districts, school districts, time zones, and the other fields.
  • USPS ZIP+4 codes and the addressee parameter.
  • Lists, Geocodio's spreadsheet upload, and batches larger than 100.
  • The distance matrix, for many origins at once.