OpenFreeMap
Quick Start Guide

This guide provides step-by-step instructions for integrating OpenFreeMap into your website or mobile application.

To get started, choose a style from the default styles provided below. Later, there’ll be options to use custom styles as well.

(You can navigate the map, it’s interactive!)

OpenFreeMap © OpenMapTiles Data from OpenStreetMap

Use the following style in a MapLibre map:

https://tiles.openfreemap.org/styles/liberty

How to load MapLibre?

Install MapLibre GL JS:

npm install maplibre-gl

Add a map container to your page:

<div id="map" style="height: 500px"></div>

Then initialize the map:

import { Map, setWorkerUrl } from 'maplibre-gl'
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url'
import 'maplibre-gl/dist/maplibre-gl.css'

// Vite worker setup
setWorkerUrl(workerUrl)

new Map({
  container: 'map',
  style: 'https://tiles.openfreemap.org/styles/liberty',
  center: [13.388, 52.517],
  zoom: 9.5,
})

For other bundlers, see MapLibre’s installation guide.

Using Mapbox?

If you are currently using Mapbox, please change your libraries to MapLibre GL JS. MapLibre is based on the last open-source version of Mapbox GL JS before it went closed-source. Migrating should be as simple as changing the libraries, as long as you are not using any features specific to the 2.x or later releases.

Using Leaflet

MapLibre GL Leaflet lets you add OpenFreeMap vector tiles to a Leaflet map.

npm install leaflet maplibre-gl @maplibre/maplibre-gl-leaflet

import * as L from 'leaflet'
import { maplibreGL } from '@maplibre/maplibre-gl-leaflet'
import { setWorkerUrl } from 'maplibre-gl'
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url'
import 'leaflet/dist/leaflet.css'
import 'maplibre-gl/dist/maplibre-gl.css'

// Vite worker setup
setWorkerUrl(workerUrl)

const map = L.map('map').setView([52.517, 13.388], 10)
maplibreGL({ style: 'https://tiles.openfreemap.org/styles/liberty' }).addTo(map)

Using OpenLayers

ol-mapbox-style creates OpenLayers layers from a MapLibre style.

npm install ol ol-mapbox-style

import Map from 'ol/Map.js'
import View from 'ol/View.js'
import LayerGroup from 'ol/layer/Group.js'
import { fromLonLat } from 'ol/proj.js'
import { apply } from 'ol-mapbox-style'
import 'ol/ol.css'

const openfreemap = new LayerGroup()
apply(openfreemap, 'https://tiles.openfreemap.org/styles/liberty')

new Map({
  target: 'map',
  layers: [openfreemap],
  view: new View({ center: fromLonLat([13.388, 52.517]), zoom: 10.5 }),
})

Mobile Apps

For mobile apps, you can use the same styles with MapLibre Native.

Custom styles

You can customize the styles using the Maputnik editor. For example, you can remove labels, POIs, or change colors.

When you use a customized style, you need to host the style JSON yourself and use its URL in MapLibre.

Customize Bright

Customize Liberty

Customize Positron

Self-hosting

You can also download our processed full planet Btrfs images if you want to self-host yourself. Details can be found on GitHub.

Start by copying config/linux_host/config.sample.jsonc to a named config such as config/linux_host/self-hosted.jsonc, then fill out your domain, certificate settings, areas (use ["monaco"] first, then ["planet", "monaco"]), and auto_update before running ./linux_host/deploy_linux_host.py --config self-hosted.

If this project helps you save on your map hosting costs, please consider sponsoring me on GitHub Sponsors.

If possible, please choose a monthly donation, even if it’s a smaller amount. The nature of this project needs recurring donations to cover the server costs.

Sponsor me

OpenFreeMapQuick Start Guide