How to access Tourism Data?

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/ui/index

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

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

Figure 18 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 19 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 20 Successful authentication.

To log out, click again on Authorize in the Swagger UI (see Figure 18), 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' \
'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.

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}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.

The following calls have been obsoleted and can not be used anymore. They have been replaced by a new filter, called language, that operates on the datasets in a similar way to the The fields Filter and is described in section The language Filter.

  • /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.

Filters common to all datasets

Note

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

Filters are used within a dataset and their primary purpose is to limit the result set according to specific parameters, although 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).

  • 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

The fields Filter

A recently added filter is the fields filter, which allows to add to a REST request a parameter that can act on multiple keys of a dataset entry, selecting only the entries which have a corresponding value in the dataset. In other words, the purpose of this filter is to retrieve only relevant information from each item in the datasets and strip down information that is not needed or not necessary to the purpose of the query. The fields filter can be used on single-valued parameters as well as on dictionary fields.

Lets take as example the ODHActivityPOI dataset and its swagger interface http://tourism.opendatahub.bz.it/swagger/ui/index#/ODHActivityPoi; the same approach can be used with other datasets by simply replacing the datasets’ name in the URL.

The following query will retrieve from the dataset only those item which have a Type and a strong:Active keys defined in the dataset:

https://tourism.opendatahub.bz.it/api/ODHActivityPoi?fields=Type,Active

The following query retrieves information from within a dictionary field:

https://tourism.opendatahub.bz.it/api/ODHActivityPoi?fields=Detail.en.Title

In particular, all items which have a Title in english within the Detail will appear in the result set of this query.

To show how it works, the following excerpt from the dataset shows how to discover the Detail.en.Title elements:

"Detail": {
  "en": {
    "Title": "01 Cross Country Stadio Track Dobbiaco/Toblach",
    "Header": null,

The language Filter

The language filter can be seen as a special case of the more generic fields filter, described in the previous section, and is similar to the second example presented there.

The language filter is used to retrieve only the data stored in one of the languages supported by the Open Data Hub. Let’s build on the example of previous section and use the ODHActivityPOI dataset. The following query will retrieve all the data in the dataset that have some information stored in English:

http://tourism.opendatahub.bz.it/api/ODHActivityPoi?language=en

Most of the data in the Open Data Hub datasets are available in three languages, English, German, and Italian, for which en, de, and it can be used as value of the language filter. Additional language in which data may be available are: Dutch (nl), Czech (cs), Polish (pl), French (fr), and Russian (ru).

The search Filter

Currently available for only a limited number of datasets, namely Accommodations, Gastronomies, Events, Activities, Pois, ODHActivitiesPois, and Article, this filters allows to find whether the given string is contained in one of the field of the JSON response sent as answer to a query.

Exporting and saving data

Queries to the Open Data Hub datasets always return data in JSON format and can be saved in that format either from the browser or from the CLI, in the latter case by simply piping the output to a file. Additionally, it is mow possible to save data also in CSV format.

Warning

This feature is currently available only for the following datasets:

Accommodation, Activity, Article, District, Event, Gastronomy, MetaRegion, Municipality, ODHActivityPoi, Poi, Region, SkiArea, SkiRegion, and TourismAssociation

However, plans are to soon have all Tourism datasets support it.

Depending on how you access the data, there are different modalities to retrieve and save data in CSV format:

  • when using a browser, append the keyword &format=csv to any query and you will be prompted to provide a name to the file that will contain the required data. Examples:

    http://tourism.opendatahub.bz.it/api/Activity?fields=Id,Detail.en.Title,ContactInfos.en.CompanyName&pagesize=500
    

    This query shows its JSON output on the screen. To save it, right click on the page and select Save as.

    http://tourism.opendatahub.bz.it/api/Activity?fields=Id,Detail.de.Title,ContactInfos.de.CompanyName&pagesize=500&format=csv
    

    Nothing is shown on screen, but a dialog window opens that allows you to select a name for the file and the directory where to save it.

  • When using a CLI command to query the Tourism endpoint, replace the header that you send with the curl command:

    curl -X GET "http://tourism.opendatahub.bz.it/api/Activity?fields=Id,Detail.en.Title,ContactInfos.en.CompanyName&pagesize=500" -H "accept: application/json"
    

    The output of this query will be in JSON format.

    curl -X GET "http://tourism.opendatahub.bz.it/api/Activity?fields=Id,Detail.en.Title,ContactInfos.en.CompanyName&pagesize=500" -H "accept: text/csv"
    

    The output of this query will be in CSV format.

  • When using an API Development Environment like Postman, add accept: text/csv to the Header of the request. See detailed procedure and screenshot can be found in the Data Exporting section of Postman’s howto.

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.

Lists

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.

Language

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.