As you may already know from the latest blog posts, new advancements are brought with the release 1.0 of the #ohsome API. One minor function involves the correctness of parameters that you can use in your queries, which was developed by our intern Rosario in the last weeks.
The new feature
Let’s say you send a request to compute the amount of residential buildings in a small area in Heidelberg on 1st of January 2015. You misspell the parameter “bboxes” and write “bbox” instead. In this case, the new feature of the ohsome API will give you a quick response back, indicating that the parameter “bbox” is unknown and it will suggest – if possible – the proper parameter to use. The response of the ohsome API will look as follows:
{"timestamp":"2020-07-13T14:58:05.346","status":400,"message":"Unknown parameter 'bbox' for this resource. Did you mean 'bboxes'?","requestUrl":"https://api.ohsome.org/v1/elements/count?bbox=8.67452,49.40961,8.70392,49.41823&time=2015-01-01&filter=building=residential and type:way"}
You could also use a parameter which is correct, but is supposed to be used for other resources. Let’s suppose you make this request. Although the ohsome API knows about the parameter “properties”, its use in this context is wrong, since “properties” doesn’t work for /elements/count (here you can find a list about which parameter works for which resource). The ohsome API will give the following message back:
“message”: “Unknown parameter ‘properties’ for this resource.”
So don’t be afraid to be wrong, the ohsome API will help you!
How it works
The new implemented feature uses a string similarity algorithm called “Fuzzy Score”: When an unfit parameter is encountered, it is compared against the list of correct parameters for the requested resource of the ohsome API. If a sequence of characters matches against a sequence of characters of a proper parameter in the list, then the algorithm will give points to this parameter. A higher final score indicates that more characters are in sequence, which implicates more similarity. Only the first two parameters with the highest score will be suggested in the response. Each of them must have at least a score of five. If the score is lower than five, you will get only an “unknown parameter” message without suggestion. We chose five because according to the behavior of the algorithm and to our set of valid parameters, a score of five is suitable as threshold to either give a suggestion (score >= 5) or don’t (score < 5). Furthermore, the algorithm is case insensitive, which means it works regardless if the parameter is written in upper or lower case letters.
Before writing the code we valuated a lot of string similarity algorithms which could have helped for our purpose. If you want to know more about it, you can start by checking this easy introduction. Also if you want to know how this feature was implemented, check the code on GitHub: StringSimilarity.java and ResourceParameters.java.
Background Info
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 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