Skip to content


Switch branches/tags
This branch is 97 commits ahead, 56 commits behind maputnik:gh-pages.

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

OSM Liberty Topo BSD licensed Build Status

OSM Liberty

A free topographic Mapbox GL basemap style for everyone with complete liberty to use and self host. OSM Liberty Topo is a fork of OSM Liberty, which is itself a fork of OSM Bright. OSM Liberty Topo is based on free data sources with a mission for a clear good looking design for the everyday user. It is based on the vector tile schema of OpenMapTiles, with contours and terrain layers from non-OpenStreetMap sources.

Preview OSM Liberty Topo

Edit OSM Liberty Topo with Maputnik


The main changes of this fork compared to the original:

  • Contours layer, using 40' contours data from USGS, created from this repository.
  • Hillshade layer, using public AWS Terrain Tiles
  • Uses Open Sans fonts instead of Roboto.
  • Puts more focus on trails
  • Includes POIs for mountain peaks, mountain passes, campsites, toilets, springs and drinking_water sources. (Note, the OSM tags natural=saddle, natural=spring and amenity=drinking_water are currently not included in the main OpenMapTiles schema. My nst-guide/openmaptiles fork includes them in the vector tiles.)


There are currently 8 style*.json files in this repository. This is because there are 4 different styles, and each style can use either WebP or PNG raster tiles. While the OSM data from OpenMapTiles is in vector format, the hillshade, NAIP imagery, and USFS topo maps are in raster format.

WebP is a newer image compression format, that is not yet supported on all browsers (specifically Safari and all iOS browsers), but WebP file sizes can be ~30-40% smaller than PNG file sizes, which mean less bandwidth cost and faster load times for users. However, because of the non-full support, it's necessary to have PNG images as a fallback.

All styles include the hillshade layer, and so all styles are duplicated, once with the WebP source, and once with the PNG source.


This is the main OSM Liberty Topo style. It includes a terrain hillshade using Mapbox Terrain RGB-compliant tiles and contours from USGS data, as well as styling for most layers in the OpenMapTiles schema.


This style superimposes selected OSM Liberty Topo layers on top of National Agriculture Imagery Program (NAIP) aerial imagery, generated from this repository. Some layers are reordered compared to the normal style.json to look better, for example, rivers/streams are superimposed on the imagery because they often aren't visible in aerial imagery, but lakes and other water bodies are hidden under the imagery because those can usually be seen in aerial imagery.

Additionally, contours are given higher contrast to show up over the imagery.


This style adds aerial imagery on top of all other layers, so that a basemap is still displayed where aerial imagery tiles don't exist.


This style adds USFS topo maps on top of all other layers, so that a basemap is still displayed where USFS topo tiles don't exist. Additionally, this superimposes the hillshade on the topo maps, for better visualization of terrain.


Currently, the only fonts used are:

  • Open Sans Regular
  • Open Sans Semibold Italic
  • Open Sans Italic

The full ranges for each of these three font stacks are hosted from the openmaptiles-fonts repository. These are downloaded from openmaptiles/fonts.


You can use this style in your Mapbox GL maps by copying the style.json file and pointing to its URL whenever Mapbox asks for a style URL.

You will, however, need to adjust the source URLs in style.json to point to other sources. For the OSM vector tiles, you can either subscribe to Maptiler Cloud or generate them yourself with the OpenMapTiles project.

You'll need to generate the contours yourself. You can find instructions here. Currently, these repositories use data from the US Geological Survey, and thus work only for the United States. Note, however, that this style can work with data created from any elevation data source as long as the layer name in the vector tiles matches the name referenced in this style.

By default, the fonts and sprites are served from this Github repository.

<!DOCTYPE html>
  <meta charset=utf-8 />
  <title>OSM Liberty Topo</title>
  <meta name='viewport' content='initial-scale=1,maximum-scale=1,user-scalable=no' />
    body { margin:0; padding:0; }
    #map { position:absolute; top:0; bottom:0; width:100%; }
  <script src=''></script>
  <link href='' rel='stylesheet' />
  <div id='map'></div>
  var map = new mapboxgl.Map({
      container: 'map',
      style: '',
      center: [-119.5936, 37.7456],
      zoom: 12,
      hash: true

  map.addControl(new mapboxgl.NavigationControl());

Data Sources

  • OpenMapTiles as vector data source
  • Natural Earth Tiles for low-zoom relief shading
  • Maki as icon set
  • Contours come from USGS 40' contour data, but could be modified to work with another international data source.
  • Terrain hillshading uses public AWS Terrain Tiles. No extra work is necessary.
  • Aerial imagery comes from the US Department of Agriculture's National Agriculture Imagery Program's openly-licensed imagery.
  • USFS Topo map tiles come from the US Forest Service.

Map Design

The map design originates from OSM Bright but strives to reach a unobtrusive and clean design for everyday use. Colored relief shading from Natural Earth make the low zoom levels look good.


You can edit the style directly online in Maputnik.

A pre-commit hook is included to validate and format the JSON styles using mapbox-gl-style-spec. To use, just install the NPM dev dependencies:

npm install

Icon Design

A Maki icon set using colors to distinguish between icon categories.

Color Palette

Color Name Hex Value
Blue #5d60be
Light Blue #4898ff
Orange #d97200
Red #ba3827
Brown #725a50
Green #76a723

Modify Icons

  1. Take the iconset.json and import it to the Maki Editor.

  2. Apply your changes and download the icons in SVG format and the iconset in JSON format.

  3. Optional: Format the JSON with cat iconset.json | jq -MS '.' for better legibility.

  4. Add the SVG files from the folder svgs_not_in_iconset to the folder svgs downloaded from the Maki Editor.

    These are the SVGs for road shields, the dot used for city and town layers and the road area pattern which could not be modified using the Maki Editor. To modify these you could use e.g. Inkscape.

  5. Install spritezero-cli: npm install -g @mapbox/spritezero-cli

  6. Generate the low resolution sprite: spritezero osm-liberty ./svgs/

  7. Generate the high resolution sprite: spritezero --retina osm-liberty@2x ./svgs/


No releases published


No packages published


  • HTML 100.0%