This is a development version of the documentation and may contain inaccuracies! Please find the official documentation at https://opendatahub.readthedocs.io/en/latest/

How to access Tourism Data?


Information in this page might be updated and improved in the next future.

The purpose of this howto is to quickly introduce the structure of the API calls, the available filters for the datasets in the Tourism domain, and give some general and useful information about the Tourism API.

Data Access and Manipulation

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

Changed in version 2019-May: new and easier procedure to authenticate and to store credentials.

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 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 17).


Figure 17 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.


Figure 18 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.


Figure 19 Successful authentication.

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

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' \


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.

Structure of the API calls

In the Tourism domain, there are a few API calls that allow to extract the same type of data from the various datasets. Each of these calls can prove useful in different scenarios, depending on the data returned and is described in this section, in which the following conventions are used:

  • {Name} is the (case sensitive!) name of the dataset you are currently working with, like for example Accomodation.
  • {Id} is the unique identifier of an array within the dataset, i.e., an item of the dataset. It is usually the first key of the resulting JSON output of a query.

The calls defined for every datasets are:

  • /api/{Name} Return the whole dataset.
  • /api/{Name}/{Id} Return only item with given {Id}.
  • /api/{Name}Localized Return the whole dataset in only the given language (which is a mandatory part of the query).
  • /api/{Name}Localized/{Id} Return only item with given Id an in given language.
  • /api/{Name}Reduced Return only the list of Ids and respective name of the items in the dataset. It is useful to create lists of items or just to have an overview of the dataset’s items.
  • /api/{Name}Changed Return all items that have changed since date YYYY-MM-DD
  • /api/{Name}Types Returns all types of data present in the dataset, that can be later used to ask more precise queries to the dataset.

Filters common to all datasets

Filters are used within a dataset and their primary purpose is to limit the result set according to specific parameters. They might not be available in every API call. information about default values can be found for each datasets in the swagger interface of the API. Some examples of their use can be found in section Quick and (not-so) Dirty Tips for Tourism (AKA Mini-howtos).


This section is Work in Progress and might be expanded.

  • Seed is used to set pagination. See tip TT3.
  • Locfilter is a composed parameters that uniquely identifies a location within South Tyrol. See example EX2 for a detailed example.
  • Latitude and Longitude are used to identify the (absolute) positioning of a location, point of interest, event, or any other type of object. They must be entered in decimal form
  • Radius it is the distance in meter prom a geographical point. It can be used together with latitude and longitude to broaden the search for an object. The results are automatically geosorted, that is, they are listed from the nearest to the most far away from the selected point. The distance is calculated as the crow flies.
  • IdFilter allows to extract from the dataset only the items with the given IDs, separated with a ,.
  • Active and OdhActive. Filters with the same name, with one prefixed by Odh refer to the same parameter. The difference is however important: Active indicates that the item is present in the original dataset provided, while OdhActive shows that the item has been verified by the Open Data Hub team and is present in the Open Data Hub. See discussion in tip TT2.
  • ODHTag allows to filter a result set according to tag defined by the Open Data Hub team. These tags are mostly related with places to see, activities that can be carried out in winter or summer, food and beverage, cultural events and so on


Besides the filters available globally, for each dataset several additional filters are available. They are described in the respective swagger interface.

Types of input data


This section is Work in Progress and will be expanded with additional types of input data.

Since calls in the tourism domain are quite generic and revolve around a few common calls (see section Structure of the API calls), we showed a couple of filters that can be used to reduce the result set and make the query more precise. Depending on the type of filter, a different type of data must be entered to have a successful result, otherwise the filter will not match. In this section we show the most common types of data that should be provided, besides the common strings, dates, and integers.

Bitmask value
A Bitmasks value is a kind of shorthand that can be entered in a filter to obtain results for different types of that filter’s accepted values. Each of the accepted values has a code that is a power of two (1, 2, 4, 8, and so on), hence each sum of different codes produces a unique number. The advantage is that, instead of entering multiple strings that should be matched, you simply need to enter a number as a filter, that is the sum of the values’ corresponding codes. See Example 3.
A list is an (unordered) sequence of items. The available values are usually listed on the right-hand side of the filter, along with the separator, which is a comma (,). In a few cases, in which more lists are accepted as filter.
Compound values
Compound values refer to those values that need a prefix before the type of value. See for example Example2 for a deeper explanation and Example 1 for a sample query that fails because a wrong compound value was supplied.
The descriptions of items in the dataset appear in three languages: Italian, German, and English. To retrieve values only in one language, enter it, de, or en, respectively.