OpenMapTiles

Fork Overview

I use OpenMapTiles with a custom topographic fork of the popular OSM Liberty style for the National Scenic Trails Guide project.

Fork changes:

• Encodes waterways and trails into the vector tiles at a lower zoom than the original OpenMapTiles project, so that they can be displayed when more zoomed out.
• Adds natural=spring and amenity=drinking_water to the POI layer.

Generating tiles

I've found that changing QUICKSTART_MAX_ZOOM in .env doesn't change the actual zoom output when the .osm.pbf extract already exists. It's a good idea to set QUICKSTART_MAX_ZOOM to a lower level like 7 to make sure the OpenMapTiles docker toolchain is working on your computer.

After you've made sure that OpenMapTiles is working, delete the .osm.pbf extract from the data/ folder, change QUICKSTART_MAX_ZOOM, and then run ./quickstart again.

More documentation is in QUICKSTART.md.

Hosting on S3

I use S3 + Cloudflare for fast, cheap hosting of map tiles. (Great tutorial for using S3 for serverless map hosting) OpenMapTiles should generate an output file like data/tiles.mbtiles. To upload to S3, first convert that .mbtiles to a directory of individual tiles with mb-util:

mb-util tiles.mbtiles tiles --image_format=pbf

Note that you must provide --image_format=pbf, otherwise the individual files will have .png extensions.

Then once you have a directory of files, you can recursively upload to S3 with

aws s3 cp tiles s3://{bucket_name}/openmaptiles/ \
    --recursive \
    --content-type application/x-protobuf \
    --content-encoding "gzip" \
    --cache-control "public, max-age=2592000, stale-while-revalidate=31536000"

I've found that the tiles won't display properly if the --content-encoding "gzip" tag isn't set. You should edit the cache-control to something suitable for your project. I don't plan to update the OSM maps more than once a month, so this caching should help keep bandwidth costs down.

Combining multiple geographies

I'm interested in combining OSM data from multiple Geofabrik regions, but I don't want to use the next higher level in the hierarchy. For example, I want to render California, Oregon, and Washington, but not all of the US or even US-west.

There are a couple possible ways to do this.

1. After you run ./quickstart.sh for each region, move the generated .mbtiles file out of the data/ directory (the .mbtiles files are removed at the beginning of each run of ./quickstart.sh). Then once you have multiple generated .mbtiles files, use tile-join (within the Tippecanoe project) to join them into a single .mbtiles file. Then finally run mb-util as above to export to a single directory.

   It should look something like this:

   git clone https://github.com/nst-guide/openmaptiles.git
   cd ./openmaptiles
   # Download all necessary OpenMapTiles programs
   docker-compose pull
   # Download and import Geofabrik extracts
   ./quickstart.sh washington
   mv data/tiles.mbtiles ./washington.mbtiles
   ./quickstart.sh oregon
   mv data/tiles.mbtiles ./oregon.mbtiles
   ./quickstart.sh california
   mv data/tiles.mbtiles ./california.mbtiles
   # Join the separate mbtiles into one
   # tile-join comes from tippecanoe
   # https://github.com/mapbox/tippecanoe
   tile-join -o joined.mbtiles washington.mbtiles oregon.mbtiles california.mbtiles
   # Export the mbtiles into a directory
   # https://github.com/mapbox/mbutil
   mb-util joined.mbtiles tiles
   # Upload the directory of tiles to S3
   aws s3 cp tiles s3://{bucket_name}/openmaptiles/ \
       --recursive \
       --content-type application/x-protobuf \
       --content-encoding "gzip" \
       --cache-control "public, max-age=2592000, stale-while-revalidate=31536000"

2. Since I'm using S3 for static tile hosting, you could probably generate each state, export each .mbtiles file to a directory, then upload each directory individually, though I haven't tested this.

   Edit: This doesn't work, because if you generate tiles for the state of Oregon, you'll have tiles that should be shared with other states that are missing data. See issue #2 for an example. So it's necessary to combine extracts with tile-join before uploading, even if you're only updating part of a region.

   Something like:

   git clone https://github.com/nst-guide/openmaptiles.git
   cd ./openmaptiles
   # Download all necessary OpenMapTiles programs
   docker-compose pull
   # Run for washington
   ./quickstart.sh washington
   mb-util data/tiles.mbtiles washington
   aws s3 cp washington s3://{bucket_name}/openmaptiles/ \
       --recursive \
       --content-type application/x-protobuf \
       --content-encoding "gzip" \
       --cache-control "public, max-age=2592000, stale-while-revalidate=31536000"
   
   # Run for oregon
   ./quickstart.sh oregon
   mb-util data/tiles.mbtiles oregon
   aws s3 cp oregon s3://{bucket_name}/openmaptiles/ \
       --recursive \
       --content-type application/x-protobuf \
       --content-encoding "gzip" \
       --cache-control "public, max-age=2592000, stale-while-revalidate=31536000"
   
   # Run for california
   ./quickstart.sh california
   mb-util data/tiles.mbtiles california
   aws s3 cp california s3://{bucket_name}/openmaptiles/ \
       --recursive \
       --content-type application/x-protobuf \
       --content-encoding "gzip" \
       --cache-control "public, max-age=2592000, stale-while-revalidate=31536000"

3. You could also try importing multiple .osm.pbf files before generating the vector tiles. I haven't tried this method in detail either. Note that you might need to manually modify the bbox and name within data/docker-compose-config.yml.

   This should be a valid way to import multiple OSM extracts into the Postgres instance within the docker setup. You should be able to import as many extracts as you have disk space for, and then run the vector tile creation on the complete database.

   I'd recommend reading quickstart.sh in more detail, as that contains all these steps with some comments.

   osm_area="washington"
   testdata=${osm_area}.osm.pbf
   # Downloads Geofabrik data, imports it, and then also creates `docker-compose-config.yml`?
   docker-compose run --rm import-osm  ./download-geofabrik.sh ${osm_area}
   make clean
   docker-compose up -d postgres
   make forced-clean-sql
   docker-compose run --rm import-water
   docker-compose run --rm import-osmborder
   docker-compose run --rm import-natural-earth
   docker-compose run --rm import-lakelines
   docker-compose run --rm import-osm
   docker-compose run --rm import-wikidata
   docker-compose run --rm import-sql
   make psql-analyze
   
   # Then do the above steps again for more osm_areas before generating the vector tiles.
   
   docker-compose up -d postserve
   # Use pre-computed docker-compose-config.yml here?
   docker-compose -f docker-compose.yml -f ./data/docker-compose-config.yml  run --rm generate-vectortiles
   docker-compose run --rm openmaptiles-tools  generate-metadata ./data/tiles.mbtiles
   docker-compose run --rm openmaptiles-tools  chmod 666         ./data/tiles.mbtiles
   docker-compose stop postgres

Using generated tiles

To use these tiles, you'll need to add a tile.json file that describes the data you've generated. This should conform to the Tile JSON specification.

It should look something like this, though you'll need to change the tiles endpoint and update the maxzoom, bounds, and center for your own data extract:

{
    "tilejson": "2.2.0",
    "name": "openmaptiles",
    "description": "OpenMapTiles",
    "version": "0.1.0",
    "attribution": "<a href=\"https://openmaptiles.org/\" target=\"_blank\">© OpenMapTiles</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">© OpenStreetMap contributors</a>",
    "scheme": "xyz",
    "tiles": [
        "https://{bucket_name}/openmaptiles/{z}/{x}/{y}.pbf"
    ],
    "minzoom": 0,
    "maxzoom": 14,
    "bounds": [-125.3321, 23.8991, -65.7421, 49.4325],
    "center": [-120.673828, 48.864681, 1]
}

Then any time you'd pass a mapbox source, like mapbox://styles/mapbox/streets-v11, instead pass the URL to your own tile.json file.

OpenMapTiles Overview

OpenMapTiles is an extensible and open tile schema based on the OpenStreetMap. This project is used to generate vector tiles for online zoomable maps. OpenMapTiles is about creating a beautiful basemaps with general layers containing topographic information. More information openmaptiles.org and openmaptiles.com.

We encourage you to collaborate, reuse and adapt existing layers, or add your own layers. You may use our approach for your own vector tile project. Feel free to fork the repo and experiment. The repository is built on top of the openmaptiles/openmaptiles-tools to simplify vector tile creation.

Please keep in mind that OpenMapTiles schema should display general topographic content. If creating a new layer or expanding an existing layer with a specific theme, please create a fork and invite other community members to cooperate on your topic. OpenMapTiles schema is used in many projects all over the world and the size of the final vector tiles needs to be considered in any update.

• 🔗 Schema https://openmaptiles.org/schema
• 🔗 Docs https://openmaptiles.org/docs
• 🔗 Production package: https://openmaptiles.com/production-package/
• 🔗 Hosting https://www.maptiler.com/cloud/
• 🔗 Create own layer https://github.com/openmaptiles/openmaptiles-skiing
• 🔗 Discuss at the #openmaptiles channel at OSM Slack

Styles

You can start from several GL styles supporting the OpenMapTiles vector schema.

🔗 Learn how to create Mapbox GL styles with Maputnik and OpenMapTiles.

• OSM Liberty Topo
• OSM Liberty
• OSM Bright
• Positron
• Dark Matter
• Klokantech Basic
• Klokantech 3D
• Fiord Color
• Toner

We also ported over our favorite old raster styles (TM2).

🔗 Learn how to create TM2 styles with Mapbox Studio Classic and OpenMapTiles.

• Light
• Dark
• OSM Bright
• Pencil
• Woodcut
• Pirates
• Wheatpaste

Schema

OpenMapTiles consists out of a collection of documented and self contained layers you can modify and adapt. Together the layers make up the OpenMapTiles tileset.

🔗 Study the vector tile schema

• aeroway
• boundary
• building
• housenumber
• landcover
• landuse
• mountain_peak
• park
• place
• poi
• transportation
• transportation_name
• water
• water_name
• waterway

Develop

To work on OpenMapTiles you need Docker.

• Install Docker. Minimum version is 1.12.3+.
• Install Docker Compose. Minimum version is 1.7.1+.

Build

Build the tileset.

git clone https://github.com/openmaptiles/openmaptiles.git
cd openmaptiles
# Build the imposm mapping, the tm2source project and collect all SQL scripts
make

You can execute the following manual steps (for better understanding) or use the provided quickstart.sh script.

./quickstart.sh

Prepare the Database

Now start up the database container.

docker-compose up -d postgres

Import external data from OpenStreetMapData, Natural Earth and OpenStreetMap Lake Labels.

docker-compose run import-water
docker-compose run import-natural-earth
docker-compose run import-lakelines
docker-compose run import-osmborder

Download OpenStreetMap data extracts and store the PBF file in the ./data directory.

cd data
wget http://download.geofabrik.de/europe/albania-latest.osm.pbf

Import OpenStreetMap data with the mapping rules from build/mapping.yaml (which has been created by make).

docker-compose run import-osm

Import latest Wikidata. If an OSM feature has Key:wikidata, OpenMapTiles check corresponding item in Wikidata and use its labels for languages listed in openmaptiles.yaml. So the generated vector tiles includes multi-languages in name field.

This step uses Wikidata Query Service to download just the Wikidata IDs that already exist in the database.

make import-wikidata

Work on Layers

Each time you modify layer SQL code run make and make import-sql.

make clean
make
make import-sql

Now you are ready to generate the vector tiles. Using environment variables you can limit the bounding box and zoom levels of what you want to generate (docker-compose.yml).

docker-compose run generate-vectortiles

License

All code in this repository is under the BSD license and the cartography decisions encoded in the schema and SQL are licensed under CC-BY.

Products or services using maps derived from OpenMapTiles schema need to visibly credit "OpenMapTiles.org" or reference "OpenMapTiles" with a link to https://openmaptiles.org/. Exceptions to attribution requirement can be granted on request.

For a browsable electronic map based on OpenMapTiles and OpenStreetMap data, the credit should appear in the corner of the map. For example:

© OpenMapTiles © OpenStreetMap contributors

For printed and static maps a similar attribution should be made in a textual description near the image, in the same fashion as if you cite a photograph.