Tourism API Howto

This howto explains how to use the Tourism API developed by the Open Data Hub team.

There are two possibilities to interact with the data exposed by the Open Data Hub’s Tourism API: You can simply browse the data using the dedicated portal or you can retrieve data and manipulated them within your application. The former method is described in Data Browsing and Exploring, while the latter is described in the next section.

Data Access and Manipulation

All the APIs available for the tourism domain can be accessed from the same URL through their swagger interface: http::/tourism.opendatahub.bz.it/swagger

For most of the Tourism domain datasets you need credentials to access the data. Go to the abovementioned URL and click on Expand Operations on the far right-hand side of LoginAPI. In the panel that opens (see Figure 8), fill in the loginmodel with your username and password.

../_images/tourism-01.png

Figure 8 Login mask of the Tourism API

To make it simpler, you can click on the Example value on the right-hand side of the page and fill in the appropriate values for username and pswd. Click on Try it out to generate a new access token that will be needed for any further request (see Figure 9).

../_images/tourism-02.png

Figure 9 Successful Token received from the LoginAPI.

After you have clicked on the button, the panel will expand and present some more data, the most important are the Curl and Response Body sections. In the first one, you can see the POST call send from the API in curl format: you can use its content to write scripts that fetch data and automatise data fetching.

The Response Body section contains the answer to the call sent and is a JSON-formatted string that contains a few data, the most important of which are:

  • The access_token, needed for any access to the data
  • The expires_in, the validity in seconds of the access token before its expiration.

To avoid writing every time the token in the API methods, copy and paste only the token without quotes from the response body into the textfield on the right-hand side textfield on top of the page (see Figure 10), then click on Explore to store the token and cache it for all the next queries.

../_images/tourism-03.png

Figure 10 Caching the received token into the tourism’ swagger interface.

Using Command Line Tools

If you plan to access the API methods with command line tools like curl or wget, or only from scripts, you need to add an authentication header to each call. For example, using curl:

curl -X GET --header 'Accept: application/json' --header \
'Authorization: Bearer vLwemAqrLKVKXsvgvEQgtkeanbMq7Xcs' \
'http://tourism.opendatahub.bz.it/api/Gastronomy'

Note

The string of the token is shortened for the sake of clarity.

It is important to mention that the authorisation header reaquires the following syntax: Authorization: Bearer, followed by the whole string of the token.

One you have retrieved the data, which come in JSON format, you can process and manipulate them with a tool like jq.

See also

More detailed documentation of the exposed API methods can be found on http://tourism.opendatahub.bz.it/Help.

Data Browsing and Exploring

If you need to only browse data, you can do so by pointing a browser to http://tourism.opendatahub.bz.it/. On the right-hand side of the page, you can see a box that shows the permissions to access data that you have as a (non-logged in) user, while the remainder of the page provides an overview of the various component of the project and its architecture.

If you try to access the ODH Data item in the top menu, you will see that it is empty. In order to access data, you need to click on the Login button on the top right corner of the page.

../_images/tourism-04.png

Figure 11 Logging in to the CMS portal.

Write the username (email address) and password that was provided to you and click on the Log in. You will be redirected to the home page as a logged in user and from here, you will see the box with the permissions you have to access the various types of data.

If you now try to access the ODH Data item in the top menu, you will be able to select some dataset. As an example, Figure 12 shows what is available in the ODH Data ‣ Activities & Pois ‣ Winter filter - in this case a list of activities that can be done during the winter on the snow.

The page allows to further filter the results, by using search strings and/or the list of tags underneath, to move between pages of results, and to change language of the interface (although at the moment the page is not fully translated in all languages!)

../_images/tourism-05.png

Figure 12 Accessing the data through filters or menu item.

If you click on one of the images in the list will pop up an overlay with more detailed information about that activity.

../_images/tourism-06.png

Figure 13 Detailed view of a POI.