OpenHistoricalMap/Reuse

From OpenStreetMap Wiki
Jump to navigation Jump to search
OpenHistoricalMap/Reuse - Other languages

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:

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 Share 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 GL JS

MapLibre GL JS is OHM's preferred client-side map library for the Web. You can either use one of the official stylesheets or design your own in a tool like Maputnik. Create a maplibregl.Map object with the URL to this stylesheet: 

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');
});

To correctly display Arabic and Hebrew text, install the mapbox-gl-rtl-text plugin. If you need to localize the labels to the user's preferred language, as on the embeddable map, also install the mapbox-gl-language plugin.

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.

MapLibre Native

MapLibre provides compatible libraries for Android and iOS. A date filtering implementation is available in Kotlin for Android: 

mapView.getMapAsync {
    it.setStyle("https://www.openhistoricalmap.org/map-styles/main/main.json") { style ->
        val localDate = LocalDate.of(2013, Month.APRIL, 14)
        style.filterLayersByDate(localDate)
    }
}

Mapbox GL JS

Since MapLibre GL JS was forked from Mapbox GL JS, both libraries share substantially equivalent support for OHM. However, we only maintain Mapbox support on a best-effort basis.

To set up an OHM-based map, follow the same steps in #MapLibre GL JS, but create a mapboxgl.Map object instead of a maplibregl.Map object. The maplibre-gl-dates plugin is only compatible with Mapbox GL JS if you install it the old-fashioned way using a <script> tag, but not if you install it using a package manager.

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:[1] 

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.

Examples

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

Notes and references

  1. ↑ Mapbox GL Leaflet is also available, but it is only compatible with leaflet-ohm-timeslider-v2, not maplibre-gl-dates.

See also

Retrieved from "https://wiki.openstreetmap.org/w/index.php?title=OpenHistoricalMap/Reuse&oldid=2809656"