Migrate from MaxMind to Mapricot
This guide moves an app's IP lookups from MaxMind to Mapricot's IP geolocation API, whether the app reads a GeoLite2 or GeoIP2 database file or calls MaxMind's web services. It shows the Mapricot request for each, how each response field carries over, and what has no equivalent. To weigh up the switch first, see Mapricot vs MaxMind.
Mapricot's API isn't compatible with MaxMind's, so each lookup changes. From a web service, it's a new URL and flatter fields. From a database file, it's a bigger change: each lookup becomes an HTTP request, and there's no file to download and update each week.
Migrate with a coding agent
Paste this prompt into Claude Code, Cursor, Codex, or another coding agent, in your project. It finds your MaxMind lookups, plans the switch with you, and makes it.
Migrate this project's IP geolocation from MaxMind to Mapricot, a location API. https://mapricot.com/guides/migrate-from-maxmind/ maps each MaxMind lookup and response field to Mapricot's, and https://mapricot.com/llms.txt lists Mapricot's docs.
1. Find every use of MaxMind in this project: GeoLite2 or GeoIP2 .mmdb files and the code that reads them, geoipupdate and other download jobs, MaxMind client libraries, and requests to geolite.info or geoip.maxmind.com. List each with what it does and which fields it uses, 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. Ask me to create a server key with the IP geolocation product at https://app.mapricot.com/ and put it in MAPRICOT_KEY, wherever this project keeps secrets. Don't ask me to paste it here.
3. Replace each lookup as the guide shows. A database lookup was local, so where the code looks up the same IP address many times, cache results for a day or more, and handle a request that fails or times out the way the code handled a missing database. Mapricot returns "found": false rather than an error for an address with no known location.
4. Credit DB-IP wherever the project shows these locations, as https://mapricot.com/docs/attribution/ explains.
5. Run the tests, and look up one real address. Then remove MaxMind's packages, database files, download jobs, and license keys, 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.
Lookups
| MaxMind | Mapricot |
|---|---|
GeoLite2 or GeoIP2 City database, reader.city(ip) |
GET /ip-geolocation/v1/{ip} |
GeoLite2 or GeoIP2 Country database, reader.country(ip) |
GET /ip-geolocation/v1/{ip}, reading the country fields |
Web service GET geolite.info/geoip/v2.1/city/{ip} |
GET /ip-geolocation/v1/{ip} |
Web service GET geoip.maxmind.com/geoip/v2.1/city/{ip} |
GET /ip-geolocation/v1/{ip} |
Web service …/city/me, for the caller |
GET /ip-geolocation/v1/{ip} with the visitor's address, read from the request on your server |
MaxMind's web services use HTTP basic authentication, with your account ID and license key. Mapricot takes its key in a header, Authorization: Bearer mapricot_sk_…. Keep that key on your server: the lookup runs there, with the visitor's IP address.
Response fields
| MaxMind | Mapricot |
|---|---|
continent.code |
continentCode |
country.iso_code |
countryCode |
country.names.en |
countryName, in English |
subdivisions[0].names.en |
regionName |
city.names.en |
city |
location.latitude, .longitude |
location.lat, .lon |
location.accuracy_radius |
None: treat the point as somewhere in the city or region |
traits.ip_address |
ip |
subdivisions[].iso_code, postal.code, location.time_zone, registered_country, traits.network |
None |
names in other languages |
None |
Address not in the data: AddressNotFoundError, or 404 from the web service |
200 with "found": false, which still counts as a request |
| A private or reserved address | 400, which isn't billed |
Mapricot leaves out fields the data doesn't have, rather than sending them empty, so check for city before using it. source, attributionUrl, licenseUrl, and datasetRelease say where the data came from and which month's release answered.
From a database file to an API
A database lookup takes microseconds and never fails once the file is loaded. An API lookup takes a network round trip and can fail, so:
- Look up once per visitor, not on every page view, and keep the answer in the session or a cache keyed by IP address. Locations change slowly, so a day is a safe time to keep one.
- Decide what happens on failure. Use a default country, as you would for an address the database didn't have, and set a short timeout so a slow lookup doesn't hold up the page.
- Delete the update job. There's no database to download, no license key for downloads, and no weekly
geoipupdaterun.
Each lookup is one request from the shared free allowance, and Mapricot doesn't write the addresses you look up to usage records or logs.
What has no equivalent
Keep these on MaxMind, or replace them with something else:
- Offline lookups from a local database file.
- Accuracy radius, postal codes, time zones, and names in languages other than English.
- The ASN, Connection Type, Anonymous IP, and ISP databases, and GeoIP Insights.
- minFraud and other fraud scoring.