MapLibre GL Dates

This is a plugin for MapLibre GL JS for filtering the map based on a date. The plugin is designed for use with OpenHistoricalMap data.

Requirements

This plugin requires MapLibre GL JS v5.6.0 and above. For Android applications written in Kotlin, an implementation of date filtering is available for MapLibre Native.

This plugin only manipulates expression syntax as defined in the MapLibre Style Specification. Support for the deprecated legacy filter syntax and the Mapbox Style Specification was discontinued in v2.0.0.

The stylesheet must be backed by a vector tileset, such as OpenHistoricalMap’s official vector tileset, that includes the following properties in each tile layer:

Property	Type	Description
start_date	String	The date the feature came into existence as a date string.
start_decdate	Number	The date the feature came into existence as a decimal year.
end_date	String	The date the feature went out of existence as a date string.
end_decdate	Number	The date the feature went out of existence as a decimal year.

A date string is a date in YYYY, YYYY-MM, or YYYY-MM-DD format, similar to ISO 8601-1 format. A decimal year is a floating-point number such that each integer represents midnight on New Year’s Day. An implementation of decimal year conversion functions is available for PL/pgSQL.

All properties are optional, but the plugin will only have an effect if one or more of these properties is present in the tileset. For performance reasons, if a given feature has a start_decdate or end_decdate property, this plugin prefers it over the start_date or end_date property.

Regardless of the data type, all dates are interpreted according to the proleptic Gregorian calendar. As there is no Year Zero, the value 1.0 falls on New Year’s Day of 1 CE, the value 0.0 falls on 1 BCE, the value -1.0 falls on 2 BCE, etc.

Installation

This plugin is available as an NPM package. To install it, run the following command:

npm install @openhistoricalmap/maplibre-gl-dates

Alternatively, you can include the plugin as a standalone script from a CDN such as unpkg.

Usage

After creating an instance of maplibregl.Map, register an event listener for the styledata event that filters the map:

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

If you set the hash option to a string when creating the Map, you can have this code respond to a date parameter in the URL hash:

map.once('styledata', function (event) {
  let params = new URLSearchParams(location.hash.substring(1));
  let date = params.get('date') || new Date();
  map.filterByDate(date);
});

And you can add a window event listener for whenever the hash changes, in order to update the filter:

addEventListener('hashchange', function (event) {
  let oldParams = new URLSearchParams(new URL(event.oldURL).hash.substring(1));
  let newParams = new URLSearchParams(new URL(event.newURL).hash.substring(1));
  let oldDate = oldParams.get('date') || new Date();
  let newDate = newParams.get('date') || new Date();
  if (oldDate !== newDate) {
    map.filterByDate(newDate);
  }
});

API

This plugin adds methods to each instance of maplibregl.Map.

filterByDate

Filters the map’s features by a date.

This function constrains each of the style layers to the global state, unless the global state already contains a date range, suggesting that the layers have already been constrained.

Parameters:

Parameter	Type	Description
date	Date or date string	The date to filter by.

A date string is defined as a date in YYYY, YYYY-MM, or YYYY-MM-DD format, similar to ISO 8601-1 format. If the date is only given to year precision, every feature overlapping that year is included; likewise, if the date is given to month precision, every feature overlapping that month is included. Negative years are supported as described in “Requirements”.

constrainStyleToDateRange

Modifies the map’s style, conditioning the filter of every layer on whether the feature properties overlap with the global date range.

The resulting filters only work if you call filterByDate() before or after.

If this function has already been called, calling it a second time results in more complex filters for no good reason. To update the date range, call filterByDate().

Feedback

Please submit bug reports and feature requests to OpenHistoricalMap’s central issue tracker, noting “maplibre-gl-dates” somewhere in the title or description.