OpenStreetMap's Wiki defines OpenStreetMap (OSM) as "a free, editable map of the whole world that is being built by volunteers largely from scratch and released with an open-content license." In some ways, it's like an open source & open data version of Google Maps. Except unlike Google maps, it is not a cohesive product that provides countless capabilities out-of-the-box. OpenStreetMap is a vast ecosystem of open source packages created by small teams of disparate maintainers building pluggable components that are powered by a multitude of technologies and programming languages. While this makes it far less cohesive than a product like Google maps, it makes it more powerful and customizable.
This article will look at various pieces of the OpenStreetMap ecosystem. OSM information is spread across many sites and hard-to-find links: this is an attempt to consolidate much of that information in one place.
openstreetmap.org
OpenStreetMap's website allows users to view & edit OpenStreetMap data. You can think of it as Wikipedia for maps. Built on top of Ruby on Rails, the site is the central repository for OpenStreetMap data that all other tools in the OSM ecosystem rely upon. The website is also a miniature showcase for OSM capabilities like map rendering, theming (available in the "layers" panel), and directions (which allows the user to pick from multiple routing services).
Most users will not consume OpenStreetMap's capabilities through its website: the data provided by the website is intended to be consumed by application developers building their own map-based applications.
OpenStreetMap data
OpenStreetMap's user-contributed data is the core of its ecosystem. With almost all of the software surrounding OSM being composed of interchangeable pieces, the data is OSM's defining quality.
The planet.openstreetmap.org subdomain provides weekly exports of the entire planet's OpenStreetMap data. It is provided as both compressed XML files and a custom Protobuf format which uses a .osm.pbf extension. At the time of writing, the compressed XML files are a little over 150gb, and they uncompress to over 2 TB according to the Wiki. The .osm.pbf Protobuf files are a little more than half the size, with the most recent being a little more than 80gb at the time of writing. In addition to being smaller, .osm.pbf can also be processed faster so they're generally the more desirable format.
Because the complete Planet dataset is so large, OSM also offers much smaller weekly changesets that can be applied to an existing planet export on a rolling basis to keep it in sync.
The exported data is typically imported into a PostgreSQL database with the PostGIS extension enabled. The data is typically imported into PostgreSQL using osm2pgsql. The full Planet data can exceed a terabyte when imported into Postgres (source, source, source), and the import process can take hours or days depending on your hardware, Postgres optimizations, and import flags. OSM's Osmosis tool can shrink the size of the data by extracting only the data that you're interested in, such as data inside of a bounding box, or extracting only the speed cameras. The OSM Wiki contains a list of other data extraction tools to reduce the dataset to the things a developer is interested in.
The most straight forward way to keep a dataset small & an import fast is to download a dataset of a single geographic area. OpenStreetMap's does not provide geographic extracts, but sites like download.openstreetmap.fr, Geofabrik, and BBBike offer regularly-updated geographic extracts. You can find more extract sources on the OSM wiki's Planet.osm page, Processed data providers page, and Switch2OSM's Serving Tiles page.
Rendering an OpenStreetMap on the web
To view an OSM map, you need a map library and a tile server. Map libraries create interactive maps using tiles provided by a tile server. Tile servers take OpenStreetMap data and render pieces of a map into individual squares that can be used by a map library.
Map libraries
Unlike commercial products like Google Maps, OpenStreetMap does not have an "official" map library that you are required to use. Among the most popular OSM map libraries for the web are Leaflet, which is the default map viewer on openstreetmap.org, and OpenLayers, which is considered more powerful but has a steeper learning curve. Alternatives like MapLibre have SDKs for web, Android, and iOS. Other popular map libraries can be found on the OSM wiki and Awesome OSM.
Tiles consumed by these map libraries can be raster tiles (images made of pixels), or vector tiles (comprised of geometries and metadata). While raster tiles can generally be used by any map library that supports them (like Leaflet), there are competing schemas for vector tiles, and a vector map library might not support all vector tile schemas.
Raster tiles
OpenStreetMap officially maintains 2 first-party raster tile server packages called mod_tile and Tirex. The rendering for these tools is powered by the open source Mapnik map generation library. Mapnik requires styles to be provided via an XML config, and a CSS-like language called CartoCSS was created by Mapbox that compiles down to Mapnik configs to make building these XML configs easier. CartoCSS was phased out by Mapbox starting in 2016 in favor of their vector tiles. Despite CartoCSS not receiving a commit since 2020 and the GitHub project being archived in 2024, the OpenStreetMap website still uses it for defining its Mapnik styles. A project called openstreetmap-carto maintains the stylesheets for the standard map layer on openstreetmap.org. To see more about how these pieces fit together, check the component overview page on the OSM wiki.
Despite being first-party, these components are not required and can be substituted with various open source packages (mbtileserver, TileServer GL, etc.) or commercial tile servers as a service (Mapbox, Stadia Maps, etc.). As long as raster tile servers follow the filename and URL path conventions, they are interchangeable. You can find additional tile server packages on the OSM Wiki.
OpenStreetMap provides a free-of-charge raster tile server at https://tile.openstreetmap.org/ that is ideal for developers to learn to build maps without having to set up their own tile server or pay a third-party tile provider. To keep it free for everyone, users must abide by its tile usage policy which prohibits bulk downloads of tiles and no-cache headers. Since this tile server provides no uptime guarantees, commercial apps should strongly consider using a paid raster tile provider or hosting their own raster tile server. If you are considering hosting your own tile server for a heavy production workload, the OSM wiki has the specs that they require for running their own production tiling servers. It's worth noting that not every single tile needs to be pre-rendered by the tile server: a recently removed Tile disk usage page on the Wiki estimates that pre-rendering every tile would take up 54tb, and less than 2% of all total tiles are actually viewed.
Vector tiles
OpenStreetMap does not officially maintain any first-party vector tile server packages, but several open source packages exist for generating and serving tiles (tilemaker, mbtileserver, Martin, etc.), along with several tile providers as a service. Vector Tiles were a project that originally came out of commercial map provider Mapbox to enable new map capabilities, like rotating a map while maintaining the text orientation. You can read more about the history of vector maps on daniel-j-h's blog post.
Mapbox created a format called Mapbox Vector Tiles (MVT) based on Google's Protobuf. It is the defacto industry standard for vector tiles and has a .mtv extension. These tiles can have different schemas (data included inside of the MVT tile). If MVT is like a CSV file, schemas are like the column names. Popular vector tile schemas include Shortbread and OpenMapTiles.
OpenStreetMap provides a free-of-charge Shortbread vector tile server at https://vector.openstreetmap.org that is ideal for developers to learn to build maps without having to set up their own tile server or pay a third-party tile provider. Like OSM's raster tile server, users must abide by its tile usage policy which prohibits bulk downloads of tiles and no-cache headers. You can see a demo of their vector tile server here.
To learn more about vector tiles, visit the OSM wiki's Vector tiles page.
Static maps
Alternatively, it is possible to render a static map to an image instead of using a map library for an interactive map (similar to Google Maps Static API). The OSM wiki static map images page provides a list of services and software packages to enable this functionality, but if you're already using Mapnik, it may be simplest to accomplish this using its Node or Python bindings.
To learn more about rendering raster, vector, or static maps, visit the OSM wiki's Rendering page.
Geocoding
Geocoding is the process of taking the name or address of a place and returning its longitude and latitude.
OpenStreetMap maintains a Python-based open source project called Nominatim for geocoding with OpenStreetMap. Nominatim uses osm2pgsql to import its data. Unfortunately, tile servers and Nominatim cannot share a database: their database schemas are incompatible. Nominatim also supports reverse geocoding, which takes a longitude and latitude and returns what is at that location.
OpenStreetMap runs a free-to-use Nominatim server, but the permitted usage is restricted: an absolute maximum of 1 request per second. Additionally, clients repeatedly sending the same query may be blocked. Because of this, you may want to consider self-hosting or using one of the commercial providers listed on the OSM wiki's Geocoding page.
Routing
Routing creates directions to get from point A to point B, much like Google Maps' directions. There are different routing tools for cars, bikes, and more.
While OpenStreetMap does not maintain any first-party routing tools, its website features OSRM, GraphHopper, and Valhalla. Additional routing software can be found on the OSM wiki's Routing page.
OpenStreetMap's license
Disclaimer: I am not a lawyer and this is not legal advice. The following section is my personal understanding of the ODbL, which may be incorrect. Do not take my interpretation as a statement of fact.
The OpenStreetMap data is covered by the Open Data Commons Open Database License (ODbL). From my reading and limited understanding, it feels like the GPL for data, but with slightly less viral copy-left enforcement. You can use the data for any purpose (including commercial), but you must attribute the source. You may create a Derivative Database by modifying or extracting data, but you must make the Derivative Database available, and that database must attribute the original source. However, things created with the Database or Derivative Database (Produced Works) may be licensed under different terms than the OBbL as long as the previously listed obligations have been met.
An interesting part of the ODbL is the idea of a Collective Database, where the data from the ODbL database is unmodified but combined with data from other independent datasets that are assembled into a collective whole. A Collective Database is not considered a Derivative Database, therefore included non-OBdL datasets that are used in conjunction with OBdL Databases are not subject to the requirements of the OBdL. We can see this in action in Apple Maps' data acknowledgement page, where they list OpenStreetMap contributors first, then list many commercial and listings below.
The Open Data Commons site includes a human readable summary of the ODbL 1.0 license, but I'd recommend reading the full license and consulting a lawyer if you have questions. Certainly take everything I've said with a grain of salt.
Attribution requirements
Things created with OpenStreetMap must attribute OpenStreetMap and make clear that the data is covered by the OBdL license. For maps, this is typically done by putting a hyperlink that says OpenStreetMap in the map's bottom right hand corner and linking to the OSM Copyright page, which has information about OpenStreetMap’s data sources as well as the ODbL. The OpenStreetMap Foundation has a Licence/Attribution Guidelines page on their website that discusses guidelines for other Produced Works such as static maps and routing engines.
Where to start
The best place to start your journey with OpenStreetMap development is the Switch2OSM website. It discusses the fundamentals of OSM in much simpler terms than this article, and has instructions for getting started with tiles using Leaflet, OpenLayers, and MapLibre. Switch2OSM also has tutorials for setting up your own tile server on Docker, Debian, and Ubuntu, but for many use cases developers can use OpenStreetMap's free tile servers and not have to set up their own.
I hope you found this post helpful. Please comment if you find incorrect information: I've been exploring the OpenStreetMap ecosystem for about a week so my understanding is limited. This post was an attempt to organize everything I've learned and keep track of links to every page I found helpful in shaping my understanding OSM.
Top comments (0)