Ohsome – a high level architectural overview of the OSM History Analytics platform

Recently we introduced the ohsome platform for OSM History Analytics. Now we want to give you a high-level overview of the ohsome platform and the components it consists of.

Ohsome API

The ohsome platform is based on a three-layers API architecture, where the flexibility, as well as the usage-complexity are increasing going from the top to the bottom.

To demonstrate how you can use the ohsome API, look at this example request:

https://api.ohsome.org/v0.9/elements/count/groupBy/boundary? bboxes=Kathmandu:85.2,27.6,85.45,27.8|Pokhara:83.9142,28.1693,84.0775,28.2687& types=way&time=2015-01-01/2017-01-01/P1M& keys=building&values=residential&showMetadata=true

The result of this request is the length of the selected elements for each month: all primary highways in the bounding box named ‘Kathmandu’ given by the coordinates of its corners. The time parameter chooses a time range (2015-01-01/2017-01-01) and requests to aggregate the result monthly (P1M).

The ohsome API is implemented using the OSHDB API, which is one level below of the ohsome API.


The OSHDB is a Java application that stores and serves the OSM history data. The OSHDB API is a functional interface that supports parallelisation of the computation based on the MapReduce programming model and, thus, may be run on a multi-instances cluster environment. The OSHDB API is more flexible but at the same time more complex than the ohsome API.

The following code-snippet shows the same example as above as a query to the OSHDB API.

  oshdb.areaOfInterest(new OSHDBBoundingBox(85.2,27.6,85.45,27.8))
    .timestamps("2015-01-01", "2017-01-01", OSHDBTimestamps.Interval.MONTHLY)
    .where("highway", "primary")
    .map((OSMEntitySnapshot t) -> Geo.lengthOf(t.getGeometry());
  SortedMap result = oshdb.sum();

OSHDB data layer
On the very bottom of the ohsome platform components stack is the OSHDB data layer. The OSHDB data layer is a specification of how the OSM data is stored, partitioned and indexed for the usage in our OSHDB. This digs deep into the core of our database and its data structures. It will leave you with a maximum of flexibility but also complexity. This is useful if you want to do crazy stuff or are a core programmer of the project.

Forthcoming posts will describe the OSHDB data layer/store format and usage in more detail. Stay tuned for updates and further examples of usage of the ohsome platform!

Comments are closed.