The Ohsome API, developed at HeiGIT, is part of the ohsome OSM history analytics platform (and yes, it is pronounced like the word „awesome“ 😉. It serves as the connection between the OpenStreetMap History Database (OSHDB) and possible frontends, such as the Ohsome Nepal Dashboard prototype. The communication with the Ohsome API works via HTTP GET and POST requests as it is based on the Representational State Transfer (REST) principle. This API is programmed in Java using the Spring Boot web-framework. The main reason behind its development is to also allow non-programmers to analyze the rich data source of the OpenStreetMap (OSM) history. It enables one to perform analysis using a dashboard-like application, or use the Ohsome API directly and work with its JSON responses.
Today we want to give a first impression on how the Ohsome API will look like. The best way to explain something is to give a working example. Therefore, you see the following link, which is used to explain the scheme of a GET request to the Ohsome API. It is a first preview using data from Nepal.
https://api.ohsome.org/v0.9/elements/count/groupBy/boundary?bboxes=Kathmandu:85.2,27.6,85.45,27.8%7CPokhara:83.9142,28.1693,84.0775,28.2687&types=way&time=2015-01-01/2017-01-01/P1M&keys=building&values=residential&showMetadata=true
Let’s analyze each component of the URL: The first part consists of the address of the server („https://api.ohsome.org") and the version of the API („/v0.9„).
Next comes the type of object that we want to request („/elements„). At the moment, „elements“ and „users“ are available.
After that, the aggregation function („/count/groupBy/boundary„) follows. In this case, we use a count function to compute the number of elements, which get grouped by the boundary (=spatial) parameter. Other possible aggregation functions would be „length„, „perimeter„, or „area„. For grouping the result, all filters can be used.
The remaining parts of the URL are parameters for filtering the data. The first one is a spatial filter („bboxes=Kathmandu:85.2,27.6,85.45,27.8|Pokhara:83.9142,28.1693,84.0775,28.2687„). We use two bounding boxes around the two largest cities of Nepal: Kathmandu and Pokhara. As their names are included in the bboxes parameter of the request, they will also be used in the response to be able to assign the results to their proper region. Other possible spatial filters would be „bcircles„, which are points with a corresponding radius and „bpolys„, which are polygons. The „bpolys“ parameter can also process GeoJSON as input.
The next part („types=way„) refers to the OSM-type. This parameter can include „node“ and/or „way“ and/or „relation„.
The temporal filter („time=2015-01-01/2017-01-01/P1M„) defines a time period of two years, in which results in a monthly interval („P1M„) are computed. The time parameter can consist of a timestamp, a time span (with intervals), or a list of timestamps.
Through the parameters „keys“ and „values„, you can filter on the OSM-tags („keys=building&values=residential„).
The last parameter („showMetadata=true„) enables the inclusion of metadata information like the computation time, or a description of the results in the response.
The current implementation of the Ohsome API combines all parameters through an „and-combination„. With having a more powerful filter system, one could request something like „Give me the length of streets that have a maxspeed of 30 OR a maxspeed of 50 AND have no name„. Going to the direction of a query language would enable further flexibility in the data-request. You can contact us at info@heigit.org if you want to give us feedback. Stay tuned for further updates!
The work at HeiGIT is kindly supported by the Klaus Tschira Foundation, Heidelberg.