Sphinx is ohsome - new documentation of the ohsome API
Jun 29th, 2020 by Fabian Kowatsch
What does the tool behind the recently published documentation of the ohsome API have in common with a statue made of stones in Egypt? - Apart from the name, both are of course awesome (and now also ohsome). As previously announced, together with the open source release 1.0 of the ohsome API, we have published a new set of documentation pages. We are giving you now a much more detailled insight in how to properly use the different endpoints and parameters of our API, as well as showing concrete examples for different endpoints. The Swagger documentation, which used to be our prime source for information of the API is still available and can be used as a playground to test simple GET requests. Let’s take a look at the different sections of the new documentation.
The main part of the docs lists the different endpoints, namely the general aggregation, user aggregation, extraction and metadata endpoints. All of them have a short description, followed by the possible aggregation, or geometry types, as well as a specific set of valid parameters. You can find further example requests for every endpoint in four different formats: GET, POST, and the two programming languages Python and R. This should help you to get a better idea on how to access our API using one of these languages. Please also note the various “! Note” windows giving additional information to the respective endpoint.
The second part displays two visualizations of the API endpoints and shows the hierarchy behind them (you can see one of the two graphs just here below). The first ones gives a graphical view on the various endpoints and the second one a rather textual one using indenting as an identifier of the hierarchy within the endpoints. Both are providing a different perspective on the same schema and summon up to a total number of 68 endpoints.
The third part of the docs can be found under the chapter “Additional Information” and comprises, as the name might suggest, of additional infos on the grouping endpoints, as well as the time, filter and spatial boundary (bboxes, bpoints, bpolys) parameters. It gives an in-depth explanation on the different posibilities that these parameters and endpoints offer and how their specific formats look like. The filter parameter is a special case, as it has just recently been introduced to the ohsome API with version 1.0 and will be presented in a follow-up post coming next week. If you want to know more about the ohsome API, or any other component of the ohsome platform, just contact us via email info@heigit.org.