How to access Tourism Data?

Changed in version 2021.05: moved technical info to dataset section

Changed in version 2021.06: removed broken URL, added browsing API section, general improvement to the content

The purpose of this howto is to quickly introduce the alternatives to access datasets in the Tourism domain. Technical information about the datasets can now be found in section Technical Information for Tourism Dataset.

Swagger Interface

All the APIs available for the tourism domain can be accessed from the same URL through their Swagger user interface:

https://tourism.api.opendatahub.bz.it/

Hint

Check section Datasets in the Tourism Domain for direct URLs to the datasets.

With the introduction on the Tourism API graphic interface of a newer swagger version, supplying and storing the token has become easier, making older procedures deprecated or obsolete. Moreover, in the new GUI, for every API method is shown whether it can provide Open Data as a result and if not, it will be necessary to authenticate.

Authentication with Swagger

Authentication is easy and, unlike it happened in the past, it does require only to supply your credentials. From the swagger UI, click on the Authorize button on the right-hand side of the page (shown in the bottom-right corner in Figure 22).

../../_images/tourism-01.png

Figure 22 The new Swagger UI for Tourism domain.

A dialog window will pop up; here, supply your username and password, and click on Authorize. It is not necessary to change any other parameter.

../../_images/tourism-02.png

Figure 23 Providing credentials for authentication.

After a few seconds a new dialog replaces the one used for authentication, whose most important bit is the Authorized word, that means you are now authenticated. No additional step is now necessary: the browser will remember the token. Click on Close to close the dialog window start browsing the Tourism data.

../../_images/tourism-03.png

Figure 24 Successful authentication.

To log out, click again on Authorize in the Swagger UI (see Figure 22), then on Logout.

Browsing API Datasets

The data in the API can be browsed at the following URL:

https://tourism.api.opendatahub.bz.it/v1/

Note

You may need to install a JSON browser plugin for your browser to browse the datasets in this way.

../../_images/API-browser.png

Figure 25 Browsing Tourism API

Here, every link can be clicked to navigate through the various datasets and the data they contain. A lot of metadata and information is provided for every object in the dataset, depending on the type of object. For example, The starting point to browse the API, shown in Figure 25 includes for each datas licensing information, a description, an ID, the API and swagger URLs, while a dataset shows the total number of items and of pages it contains, the current page, pointers to previous and next page, and the items themselves.

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.