OpenHistoricalMap/Reuse

As an open data project, OpenHistoricalMap encourages you to reuse the data in your own research and creative projects.

Processing the data

Vector tiles and stylesheets

You can embed an OpenHistoricalMap-based map on your website or in your native application using either Mapbox GL or MapLibre.

The stylesheets on the OpenHistoricalMap website conform to the Mapbox Style Specification and MapLibre Style Specification, so you can set your map to one of these styles directly:

• Historic
• Railway
• Japanese Scroll
• Woodblock

Or if you prefer to write your own style, you can point it to OpenHistoricalMap vector tiles using the following URL template:

https://vtiles.openhistoricalmap.org/maps/osm/{z}/{x}/{y}.pbf

The layout of each vector tile is defined in a series of TOML files. You can inspect the tiles' contents using this Tegola inspector.

Whether you use an existing style or create your own, you will need to filter the features by the start_decdate and end_decdate properties, which correspond to the start_date=* and end_date=* tags converted to decimal years.

QGIS

Main article: OpenHistoricalMap/QGIS

For more advanced visualizations that require desktop processing, OpenHistoricalMap/QGIS can load OpenHistoricalMap tiles and stylesheets directly, or it can query the Overpass API for more selective data processing.

Displaying a map

There are several ways to display an interactive map on a webpage.

Embed

The easiest method is to visit the OHM homepage, navigate to the place and time of interest, and click the button on the right side of the map. Inside the Share panel, change the format from "Link" to "HTML", then copy the provided HTML code.

This embed loads embed.openhistoricalmap.org in an iframe. The source code for this embed is also available in the openhistoricalmap-embed repository.

MapLibre

MapLibre GL JS is OHM's preferred client-side map library for the Web. When creating your maplibregl.Map object, set the style to one of the official stylesheets or your own, for example:

const map = new maplibregl.Map({
  container: 'map',
  style: 'https://www.openhistoricalmap.org/map-styles/main/main.json',
  attributionControl: {
    customAttribution: '<a href="https://www.openhistoricalmap.org/">OpenHistoricalMap</a>',
  },
});

You will also need to install and configure the maplibre-gl-dates plugin to filter the map by date, in order to prevent anachronisms:

map.once('styledata', function (event) {
  map.filterByDate('2013-04-14');
});

Please credit OpenHistoricalMap contributors on or near the map. You can easily provide attribution by setting the attribution option when initializing the L.maplibreGL object.

Leaflet

Many content management systems and website frameworks integrate Leaflet, a library for rendering raster maps. Since we don't publish a raster tile layer, you'll still need to install MapLibre GL JS, as well as the MapLibre GL Leaflet plugin to tie the two libraries together:

const gl = L.maplibreGL({
  style: 'https://www.openhistoricalmap.org/map-styles/main/main.json',
  attributionControl: '<a href="https://www.openhistoricalmap.org/">OpenHistoricalMap</a>'
}).addTo(map);

To prevent anachronisms, you will need to filter the map by date. The OpenHistoricalMap Timeslider plugin handles the filtering step and provides a friendly user interface for adjusting the year to filter by. Alternatively, you can install and configure the maplibre-gl-dates plugin and build your own control for choosing the date:

const maplibreMap = gl.getMaplibreMap();
maplibreMap.once('styledata', function (event) {
  maplibreMap.filterByDate('2013-04-14');
});

OSM-OHM is a Leaflet widget that overlays specific OHM ways or relations atop an OpenStreetMap base map.

Querying the data

Overpass

Main article: OpenHistoricalMap/Overpass

OpenHistoricalMap's Overpass API instance allows you to query the database for elements matching very specific criteria. For example, you could search for trees that were planted in a certain city during a particular date range near a certain kind of building – all subject to whether these details have been mapped, of course. You can query OpenHistoricalMap's Overpass API instance directly over HTTPS or using Overpass turbo or Overpass Ultra within a Web browser.

QLever

Main article: OpenHistoricalMap/QLever

QLever provides an endpoint for rapidly querying the global OpenHistoricalMap dataset. As with the Overpass API, you can query for arbitrary, specific criteria; however, you use the standard query language SPARQL. SPARQL queries can federate with a number of other datasets, including OpenStreetMap and Wikidata. QLever can display results as a table, map, or heatmap.

Nominatim

OpenHistoricalMap's Nominatim instance lets you search for features by name or a limited selection of other search terms. The API endpoint is located at:

https://nominatim-api.openhistoricalmap.org/

A Web interface provides extra information that can be useful in diagnosing unexpected results.

Planet

For high-volume data processing, the entire contents of the OpenHistoricalMap database are available in planet.osm format on Amazon s3. Browse the available planet files. A new planet file containing the current database contents is generated daily. A more complete planet file, containing the database's full revision history, is generated weekly. The revision history allows you to track changes in the database over time, not to be confused with real-world changes over time.

If you do not need all the data about every place in all of history, consider extracting a part of the database using Overpass or the REST API. We do not have a regional extract service at the moment, but please let us know if you are able to provide such a service.

REST API

OpenHistoricalMap's main REST API allows you to upload and download raw data in OSM XML format. This is generally only useful to developers of OpenHistoricalMap software. However, if you have a node, way, or relation ID and simply need to look up its raw tags, this would be the fastest and most up-to-date method. The API endpoint is located at:

https://www.openhistoricalmap.org/api/0.6/

Legal considerations

In general, OpenHistoricalMap data is in the public domain under a CC0 dedication. As a courtesy, please credit OpenHistoricalMap contributors where appropriate. Some individual features may have additional legal requirements around attribution, as detailed in Open Historical Map/Copyright and Open Historical Map/OHM Contributors.

Examples

For inspiration, here are some examples of mashups that incorporate OpenHistoricalMap data:

• Gramps Web
• GlobStory.it / HistoryAI
• Richard Welty's Ghost Tracks prototype
• Mapy židovského osídlení 1857–1930 – interactive map of the historic Jewish populations of several Czech towns by Daniel Baránek
• Mashup of OpenStreetMap (Shortbread) vector tiles and historic railways from OpenHistoricalMap

See also

• Bibliography of works using OpenHistoricalMap as source material