Migrate from MapTiler to Mapricot
This guide moves an app's MapTiler maps and API calls to Mapricot. It lists the Mapricot replacement for each MapTiler product, how each parameter and response field carries over, and what has no equivalent. To weigh up the switch first, see Mapricot vs MapTiler.
Maps move with the least change: both serve MapLibre styles. Geocoding calls change more, since MapTiler returns GeoJSON with coordinates as [lon, lat], and Mapricot returns a results list with lat and lon by name.
Migrate with a coding agent
Paste this prompt into Claude Code, Cursor, Codex, or another coding agent, in your project. It finds your MapTiler calls, plans the switch with you, and makes it.
Migrate this project from MapTiler to Mapricot, a location API. https://mapricot.com/guides/migrate-from-maptiler/ maps each MapTiler product, parameter, and response field to Mapricot's, and https://mapricot.com/llms.txt lists Mapricot's docs.
1. Find every use of MapTiler in this project: api.maptiler.com style and tile URLs, the @maptiler/sdk package and its geocoding control, and geocoding and geolocation requests. List each with what it does and what replaces it, and tell me about any that Mapricot can't replace, such as custom styles from MapTiler's style editor. 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 maps and other code in web pages, use a browser key: create one with the create_key tool if you have Mapricot's MCP server, or ask me to. 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 either here.
3. Replace @maptiler/sdk with maplibre-gl and point maps at Mapricot's styles, as https://mapricot.com/docs/map-tiles/ shows. Replace geocoding calls as the guide shows: MapTiler uses [lon, lat], and Mapricot takes and returns lat and lon by name. Mapricot rejects unknown parameters with a 400, so drop MapTiler 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, load each map in a browser, and make one real request to each endpoint you changed. Then remove MapTiler'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
| MapTiler | Mapricot |
|---|---|
api.maptiler.com/maps/{style}/style.json |
/tiles/v1/styles/{style}.json |
@maptiler/sdk |
maplibre-gl |
GET /geocoding/{query}.json |
GET /geocoding/v1/search, or autocomplete as people type |
GET /geocoding/{lon},{lat}.json |
GET /geocoding/v1/reverse |
GET /geocoding/{id}.json |
GET /places/v1/{id}, for a Mapricot ID |
GET /geocoding/{query1};{query2}.json, a batch |
POST /geocoding/v1/search/batch, up to 100 searches |
GET /geolocation/ip.json, for the caller |
GET /ip-geolocation/v1/{ip}, for any IP address |
MapTiler takes its key as key in the URL. Mapricot's map styles do too, as ?key=, and its other endpoints take the key in a header, Authorization: Bearer mapricot_sk_…. MapTiler feature IDs don't work with Mapricot, so search again for any place you saved by its MapTiler ID.
Maps
The MapTiler SDK extends MapLibre GL JS, so most map code carries over. Swap the package and the style:
npm uninstall @maptiler/sdk
npm install maplibre-gl
import * as maplibregl from "maplibre-gl";
import "maplibre-gl/dist/maplibre-gl.css";
const map = new maplibregl.Map({
container: "map",
style: `https://api.mapricot.com/tiles/v1/styles/default.json?key=${import.meta.env.VITE_MAPRICOT_KEY}`,
center: [-122.6793, 45.5189],
zoom: 15,
});
- The key. Delete
maptilersdk.config.apiKey. The Mapricot style takes a browser key with the Map tiles product in its URL. - The style.
MapStyle.STREETSand other MapTiler style constants become a Mapricot style URL:default,light,dark,bright,grayscale, oroutdoors. - The worker. Under Vite, MapLibre GL JS 6 needs its worker's URL set, as Migrate from Mapbox GL JS to MapLibre shows.
- Everything else, such as
Marker,Popup,addSource, andaddLayer, is MapLibre's own and keeps working.
Controls the SDK adds, such as its geolocate, terrain, and projection controls, have MapLibre equivalents or are dropped. Layers you add on top of MapTiler's style keep working, but layers that refer to MapTiler's own sources need Mapricot's: Custom map styles explains them.
Geocoding
| MapTiler | Mapricot |
|---|---|
{query} in the path |
q |
proximity=-122.68,45.52 |
focus=45.52,-122.68, in lat,lon order |
proximity=ip |
Find the location with IP geolocation first, then pass it as focus |
country=us,ca |
country=us,ca, up to 10 codes |
language |
lang, one language |
limit |
limit, up to 20 |
autocomplete=true, the default |
Use the autocomplete endpoint |
autocomplete=false |
Use the search endpoint |
Reverse: {lon},{lat} in the path |
Reverse: lat and lon parameters |
bbox, types, excludeTypes, fuzzyMatch, worldview |
None. Filter on each result's type instead of types |
MapTiler features[] |
Mapricot results[] |
|---|---|
center, as [lon, lat] |
lon, lat |
place_name |
label |
text |
name |
id |
id |
place_type, such as address, street, or municipality |
type, such as address, street, or locality |
address |
address.houseNumber |
context[], a list of the areas around the result |
address, with street, postalCode, locality, region, regionCode, country, and countryCode by name |
properties.country_code |
address.countryCode |
relevance, bbox, matching_text, matching_place_name |
None |
MapTiler's address context is a list to search by id prefix. Mapricot's address is an object, so that search becomes a field read.
If you use the MapTiler SDK's geocoding control, the MapLibre search box guide builds one on Mapricot's autocomplete.
IP geolocation
MapTiler's geolocation looks up the caller. Mapricot looks up any IP address you give it, so a server looks up its visitor's IP: GET /ip-geolocation/v1/{ip}.
| MapTiler | Mapricot |
|---|---|
country, country_code |
countryName, countryCode |
region |
regionName |
city |
city |
continent_code |
continentCode |
latitude, longitude |
location.lat, .lon |
timezone, postal, eu |
None |
What has no equivalent
Keep these on MapTiler, or replace them with something else:
- Custom styles made in MapTiler's style editor, satellite imagery, and terrain and hillshade tiles.
- Hosting your own data as tiles, and static maps.
- The Coordinates, Elevation, and Weather APIs.