Home

Awesome

Planetiler

Planetiler (pla·nuh·tai·lr, formerly named "Flatmap") is a tool that generates Vector Tiles from geographic data sources like OpenStreetMap. Planetiler aims to be fast and memory-efficient so that you can build a map of the world in a few hours on a single machine without any external tools or database.

Vector tiles contain raw point, line, and polygon geometries that clients like MapLibre can use to render custom maps in the browser, native apps, or on a server. Planetiler packages tiles into an MBTiles (sqlite) or PMTiles file that can be served using tools like TileServer GL or Martin or even queried directly from the browser. See awesome-vector-tiles for more projects that work with data in this format.

Planetiler works by mapping input elements to vector tile features, flattening them into a big list, then sorting by tile ID to group into tiles. See ARCHITECTURE.md for more details or this blog post for more of the backstory.

Demo

See the live demo of vector tiles created by Planetiler and hosted by OpenStreetMap US.

Planetiler Demo Screenshot © OpenMapTiles © OpenStreetMap contributors

Usage

To generate a map of an area using the OpenMapTiles profile, you will need:

To build the map:

Using Java, download planetiler.jar from the latest release and run it:

wget https://github.com/onthegomap/planetiler/releases/latest/download/planetiler.jar
java -Xmx1g -jar planetiler.jar --download --area=monaco

Or using Docker:

docker run -e JAVA_TOOL_OPTIONS="-Xmx1g" -v "$(pwd)/data":/data ghcr.io/onthegomap/planetiler:latest --download --area=monaco

:warning: This starts off by downloading about 1GB of data sources required by the OpenMapTiles profile including ~750MB for ocean polygons and ~240MB for Natural Earth Data.

<details> <summary>To download smaller extracts just for Monaco:</summary>

Java:

java -Xmx1g -jar planetiler.jar --download --area=monaco \
  --water-polygons-url=https://github.com/onthegomap/planetiler/raw/main/planetiler-core/src/test/resources/water-polygons-split-3857.zip \
  --natural-earth-url=https://github.com/onthegomap/planetiler/raw/main/planetiler-core/src/test/resources/natural_earth_vector.sqlite.zip

Docker:

docker run -e JAVA_TOOL_OPTIONS="-Xmx1g" -v "$(pwd)/data":/data ghcr.io/onthegomap/planetiler:latest --download --area=monaco \
  --water-polygons-url=https://github.com/onthegomap/planetiler/raw/main/planetiler-core/src/test/resources/water-polygons-split-3857.zip \
  --natural-earth-url=https://github.com/onthegomap/planetiler/raw/main/planetiler-core/src/test/resources/natural_earth_vector.sqlite.zip

You will need the full data sources to run anywhere besides Monaco.

</details>

To view tiles locally:

Using Node.js:

npm install -g tileserver-gl-light
tileserver-gl-light data/output.mbtiles

Or using Docker:

docker run --rm -it -v "$(pwd)/data":/data -p 8080:8080 maptiler/tileserver-gl -p 8080

Then open http://localhost:8080 to view tiles.

Some common arguments:

Git submodules

Planetiler has a submodule dependency on planetiler-openmaptiles. Add --recurse-submodules to git clone, git pull, or git checkout commands to also update submodule dependencies.

To clone the repo with submodules:

git clone --recurse-submodules https://github.com/onthegomap/planetiler.git

If you already pulled the repo, you can initialize submodules with:

git submodule update --init

To force git to always update submodules (recommended), run this command in your local repo:

git config --local submodule.recurse true

Learn more about working with submodules here.

Generating a Map of the World

See PLANET.md.

Generating Custom Vector Tiles

If you want to customize the OpenMapTiles schema or generate an mbtiles file with OpenMapTiles + extra layers, then fork https://github.com/openmaptiles/planetiler-openmaptiles make changes there, and run directly from that repo. It is a standalone Java project with a dependency on Planetiler.

If you want to generate a separate mbtiles file with overlay layers or a full custom basemap, then:

If you want to customize how planetiler works internally, then fork this project, build from source, and consider contributing your change back for others to use!

Benchmarks

Some example runtimes for the OpenMapTiles profile (excluding downloading resources):

InputVersionMachineTimeoutput sizeLogs
s3://osm-pds/2024/planet-240115.osm.pbf (69GB)0.7.0c3d-standard-180 (180cpu/720GB)22m cpu:44h34m avg:12069GB pmtileslogs
s3://osm-pds/2024/planet-240108.osm.pbf (73GB)0.7.0c7gd.16xlarge (64cpu/128GB)42m cpu:42m28s avg:5269GB pmtileslogs
s3://osm-pds/2022/planet-220530.osm.pbf (69GB)0.5.0c6gd.16xlarge (64cpu/128GB)53m cpu:41h58m avg:47.179GB mbtileslogs, VisualVM Profile
s3://osm-pds/2022/planet-220530.osm.pbf (69GB)0.5.0c6gd.8xlarge (32cpu/64GB)1h27m cpu:37h55m avg:26.179GB mbtileslogs
s3://osm-pds/2022/planet-220530.osm.pbf (69GB)0.5.0c6gd.4xlarge (16cpu/32GB)2h38m cpu:34h3m avg:12.979GB mbtileslogs

Merging nearby buildings at z13 is very expensive, when run with --building-merge-z13=false:

InputVersionMachineTimeoutput sizeLogs
s3://osm-pds/2024/planet-240115.osm.pbf (69GB)0.7.0c3d-standard-180 (180cpu/720GB)16m cpu:27h45m avg:10469GB pmtileslogs
s3://osm-pds/2024/planet-240108.osm.pbf (73GB)0.7.0c7gd.16xlarge (64cpu/128GB)29m cpu:23h57 avg:5069GB pmtileslogs
s3://osm-pds/2024/planet-240108.osm.pbf (73GB)0.7.0c7gd.2xlarge (8cpu/16GB)3h35m cpu:19h45 avg:5.569GB pmtileslogs
s3://osm-pds/2024/planet-240108.osm.pbf (73GB)0.7.0im4gn.large (2cpu/8GB)18h18m cpu:28h6m avg:1.569GB pmtileslogs
s3://osm-pds/2022/planet-220530.osm.pbf (69GB)0.5.0c6gd.16xlarge (64cpu/128GB)39m cpu:27h4m avg:42.179GB mbtileslogs, VisualVM Profile

Alternatives

Some other tools that generate vector tiles from OpenStreetMap data:

Some companies that generate and host tiles for you:

If you want to host tiles yourself but have someone else generate them for you, those companies also offer plans to download regularly-updated tilesets.

Features

Limitations

Use as a library

Planetiler can be used as a maven-style dependency in a Java project using the settings below:

Maven

Add this repository block to your pom.xml:

<repositories>
  <repository>
    <id>osgeo</id>
    <name>OSGeo Release Repository</name>
    <url>https://repo.osgeo.org/repository/release/</url>
    <snapshots>
      <enabled>false</enabled>
    </snapshots>
    <releases>
      <enabled>true</enabled>
    </releases>
  </repository>
</repositories>

Then add the following dependency:

<dependency>
  <groupId>com.onthegomap.planetiler</groupId>
  <artifactId>planetiler-core</artifactId>
  <version>${planetiler.version}</version>
</dependency>

Gradle

Set up your repositories block::

mavenCentral()
maven {
    url "https://repo.osgeo.org/repository/release/"
}

Set up your dependencies block:

implementation 'com.onthegomap.planetiler:planetiler-core:<version>'

Contributing

Pull requests are welcome! See CONTRIBUTING.md for details.

Support

For general questions, check out the #planetiler channel on OSM-US Slack (get an invite here), or start a GitHub discussion.

Found a bug or have a feature request? Open a GitHub issue to report.

This is a side project, so support is limited. If you have the time and ability, feel free to open a pull request to fix issues or implement new features.

Acknowledgement

Planetiler is made possible by these awesome open source projects:

See NOTICE.md for a full list and license details.

Author

Planetiler was created by Michael Barry for future use generating custom basemaps or overlays for On The Go Map.

License and Attribution

Planetiler source code is licensed under the Apache 2.0 License, so it can be used and modified in commercial or other open source projects according to the license guidelines.

Maps built using planetiler do not require any special attribution, but the data or schema used might. Any maps generated from OpenStreetMap data must visibly credit OpenStreetMap contributors. Any map generated with the profile based on OpenMapTiles or a derivative must visibly credit OpenMapTiles as well.