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.

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

Terminal
npm uninstall @maptiler/sdk
npm install maplibre-gl
main.js
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.STREETS and other MapTiler style constants become a Mapricot style URL: default, light, dark, bright, grayscale, or outdoors.
  • 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, and addLayer, 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.