ohsome API v1.1 - changes and new functionalities
Sep 14th, 2020 by Fabian Kowatsch
Recently we’ve had the first minor release 1.1 of the ohsome API, which brings several new features and upgrades. In the following lines we want to present to you the most important ones.
Prior to 1.1, when you were requesting data through one of our data extraction endpoints, you would always get the geometries clipped to the given spatial boundary|boundaries. With the addition of the parameter clipGeometry, you can now specify by yourself if you want to get them clipped (clipGeometry=true) or unclipped (clipGeometry=false). The default behavior is having clipping of the features enabled, as we want to ensure backwards compatibility. To demonstrate a use case we’ve prepared an example request where we take a look at the buildings within a 2km catchment area of the football stadium of TSG Hoffenheim in Sinsheim. The graphic shows the buildings with an unclipped geometry in purple overlayed with the clipped features in orange.
You can clearly see the cut of the boundary through the buildings. Using clipped geometries could make sense if someone is computing aggregations of the features in the given region, e.g. to get the length of the road network. When extracting and visualizing data, like in the given example, it is better though to disable the clipping. Here are the example URLs of clipped vs. unclipped.
The second new feature comes along with an upgrade of the ohsome filter library to 1.2 bringing the following two new filter functionalities:
- having a “tag key in value-list” operator to select a specific set of tags having the same key
- filter example: filter=highway in (residential, living_street)
- request example: give the length of residential and living streets (URL)
- selecting features by their OSM ID, either through giving one particular ID, a list of IDs or a range of IDs; it should always be combined with an OSM type
- filter examples: filter=type:way and id:12345 filter=type:reladion and id:(1, 2, 3) filter=type:way and id:(1 .. 123)
- request example: select one specific OSM feature (URL)
Of course these new filters are also documented within the dedicated filter documentation page.
Apart from these changes, there have been a few updates on the GitHub readme, as well as stuff that only affects the code itself, like the increase of the Java compatibility to version 11 or diverse smaller bug fixes and code refactorings. The full list of changes can be found in the changelog of the ohsome API GitHub repository. Have fun with using the new features and remember: stay ohsome!
Context: the aim of the ohsome OpenStreetMap History Data Analytics Platform is to make OpenStreetMap’s full-history data more easily accessible for various kinds of OSM data analytics tasks, such as data quality analysis, on a global scale. The ohsome API is one of its components, providing free and easy access to some of the functionalities of the ohsome platform via HTTP requests. Some intro can be found here:
- ohsome general idea
- ohsome general architecture
- the whole “how to become ohsome” tutorials series
- how to make a query
- integration of simple feature keywords in the filters of the ohsome API.
- how spatial joins queries work in the OpenStreetMap History Database OSHDB