Migrate from OpenFreeMap to Mapricot
This guide moves a map from OpenFreeMap's styles to Mapricot's free map tiles. It shows which style replaces each of OpenFreeMap's, what to change in MapLibre, Leaflet, and OpenLayers, and what to do about layers written for OpenFreeMap's tiles. To weigh up the switch first, see Mapricot vs OpenFreeMap.
Both serve MapLibre styles, so for most maps the change is one URL and a key. Maps that add layers drawn from OpenFreeMap's own tiles take more work, because the two use different tile schemas: OpenFreeMap uses OpenMapTiles, and Mapricot uses Protomaps.
Migrate with a coding agent
Paste this prompt into Claude Code, Cursor, Codex, or another coding agent, in your project. It finds your OpenFreeMap maps, plans the switch with you, and makes it.
Migrate this project's maps from OpenFreeMap to Mapricot's map tiles. https://mapricot.com/guides/migrate-from-openfreemap/ explains what changes, and https://mapricot.com/llms.txt lists Mapricot's docs.
1. Find every use of OpenFreeMap in this project: tiles.openfreemap.org style and tile URLs, in MapLibre, Leaflet, OpenLayers, or mobile code. Also find layers that use OpenFreeMap's tile source, the "openmaptiles" source or its source-layers such as transportation, water, or place, and layers added before one of OpenFreeMap's layer IDs. List each with what it does and what replaces it. Wait for my OK before changing code.
2. Get a browser key with the Map tiles product: create one with the create_key tool if you have Mapricot's MCP server, for this site's origins and http://localhost:*, or ask me to create one at https://app.mapricot.com/. Mobile apps need a server key with Map tiles instead. Put the key where this project keeps its settings.
3. Replace each style URL with the Mapricot style the guide suggests. Rewrite layers that use OpenFreeMap's tiles for Mapricot's Protomaps-schema tiles, as the guide shows, and leave layers that draw this project's own data as they are.
4. Load each map in a browser and check that it draws, with its credit in the corner. Then 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.
Styles
| OpenFreeMap | Mapricot |
|---|---|
https://tiles.openfreemap.org/styles/liberty |
https://api.mapricot.com/tiles/v1/styles/default.json?key=mapricot_pk_… |
…/styles/bright |
…/styles/bright.json?key=… |
…/styles/positron |
…/styles/light.json?key=… |
…/styles/dark or …/styles/fiord |
…/styles/dark.json?key=… |
| None | …/styles/grayscale.json?key=… and …/styles/outdoors.json?key=… |
…/styles/3d |
None |
Map tiles shows each Mapricot style. The styles look different from OpenFreeMap's, so check each map after switching.
The key
OpenFreeMap needs no key. Mapricot's styles take a free one in their URL, and map loads are never billed:
- For a web page, create a browser key with the Map tiles product, and list your site under Allowed origins, such as
https://example.com, withhttp://localhost:*while you build. The key is visible in the page, and works only from those origins. - For a mobile app, which sends no origin, create a server key with only the Map tiles product.
API keys explains each setting.
MapLibre, Leaflet, and OpenLayers
In each, change the style URL and nothing else:
new maplibregl.Map({
container: "map",
style: "https://api.mapricot.com/tiles/v1/styles/default.json?key=mapricot_pk_…",
center: [13.388, 52.517],
zoom: 9.5,
});
maplibreGL({ style: "https://api.mapricot.com/tiles/v1/styles/default.json?key=mapricot_pk_…" }).addTo(map);
apply(layerGroup, "https://api.mapricot.com/tiles/v1/styles/default.json?key=mapricot_pk_…");
MapLibre Native on iOS and Android takes the same URL, with a server key. React Leaflet and Leaflet vs OpenLayers vs MapLibre show fuller examples in each library.
Layers of your own
Layers that draw your own data, from a GeoJSON source or your own tiles, keep working on Mapricot's styles. Two kinds of layer need changes:
- Layers that draw OpenFreeMap's tiles, such as a layer with
source: "openmaptiles"and"source-layer": "transportation"to highlight roads. Mapricot's tiles follow the Protomaps schema, with different layer names and properties: OpenMapTiles'transportationisroads,wateriswater,buildingisbuildings,placeisplaces, andpoiispois, and the properties inside them differ too. Point such a layer at Mapricot's source and rewrite its filter for the Protomaps layer. Custom map styles shows how. - Layers added before one of OpenFreeMap's layers, as in
map.addLayer(layer, "building"). Mapricot's styles have different layer IDs, so pick one from the new style, or leave the argument out to draw on top.
A style of your own built for OpenMapTiles, such as one exported from Maputnik, needs the same rewrite for each layer, or a fresh start from Mapricot's styles.
What has no equivalent
Keep these on OpenFreeMap, or replace them with something else:
- The 3D style and OpenFreeMap's other style designs.
- The OpenMapTiles schema, for styles built for it.
- Weekly planet downloads for running your own tile server.