Quick and (not-so) Dirty Tips for Tourism (AKA Mini-howtos)

This section contains various tips and tricks to improve and tweak the queries sent to the Tourism datasets, allowing more precise results to be retrieved. This page is divided into two parts: The first one shows examples with code (usually the API call), the second is organised like a FAQ section.

Example Calls

EX1. Why does this query return no result?

https://tourism.api.opendatahub.com/v1Gastronomy?pagesize=3&categorycodefilter=0&locfilter=reg268

Because there is no value reg268 for locfilter. You can return valid IDs to be used as locfilter using this call:

https://tourism.api.opendatahub.com/v1RegionReduced?language=it

An example result for this call is:

{
  "Id": "D2633A26C24E11D18F1B006097B8970B",
  "Name": "Alta Badia"
}

Therefore, use the ID regD2633A26C24E11D18F1B006097B8970B in locfilter to search for Gastronomy in the Alta Badia region.

EX2. The locfilter parameter.

Q: How do I correctly use the locfilter parameter?

locfilter =>
Locfilter (Separator ',' possible values: reg + REGIONID = (Filter by
Region), reg + REGIONID = (Filter by Region), tvs + TOURISMVEREINID =
(Filter by Tourismverein), mun + MUNICIPALITYID = (Filter by
Municipality), fra + FRACTIONID = (Filter by Fraction)),
(default:'null')

It seems to accept a string, but how is this string built?

A: locfilter accepts a string composed as follows: a region identifier, followed immediately by a location Identifier.

Location identifier are the following four:

  • reg: Region (Italian Regione)
  • tvs: Turistic association (German Tourismusverein)
  • mun: Municipality, i.e., town or city (Italian Municipalità)
  • fra: Suburb or district (Italian frazione)

IDs for each location can be gathered either from the swagger interface or using an API calls:

For example, to retrieve all Gastronomy in the suburb of Lana, first retrieve its ID, which is:

{
  "Id": "79CBD79551C911D18F1400A02427D15E",
  "Name": "Lana"
}

Then pass the string fra79CBD79551C911D18F1400A02427D15E as locfilter:

EX3. The categorycodefilter parameter.

Q: categorycodefilter seems similar to the locfilter parameter found in this trick, but this does not accept string?

Category Code Filter (BITMASK values: 1 = (Restaurant), 2 = (Bar /
Café / Bistro), 4 = (Pub / Disco), 8 = (Apres Ski), 16 =
(Jausenstation), 32 = (Pizzeria), 64 = (Bäuerlicher Schankbetrieb),
128 = (Buschenschank), 256 = (Hofschank), 512 = (Törggele Lokale),
1024 = (Schnellimbiss), 2048 = (Mensa), 4096 = (Vinothek /Weinhaus /
Taverne), 8192 = (Eisdiele), 16348 = (Gasthaus), 32768 = (Gasthof),
65536 = (Braugarten), 131072 = (Schutzhütte), 262144 = (Alm), 524288 =
(Skihütte)

The categorycodefilter parameter accepts integers instead of strings, in bitmask-value. The code of each category is a power of 2, so to search in multiple categories, simply add the respective codes and pass them as value of the parameter. For example, to search for Restaurants (1) and Pizzerias (32), pass 33 to categorycodefilter:

Tips and Tricks

TT1. Categorycodefilter in the Accomodation dataset.

Q: In the Accommodation dataset there’s no categorycodefilter filter, like in the Gastronomy dataset. Is there some equivalent filter?

A: In the Accommodations dataset use categoryfilter instead.

TT2. odhactive and filters starting with odh.

Q: What is the purpose of the odhactive filter? And what do all the filters prefixed with odh stand for?

A: In the datasets, there are filters like active and odhactive, where odh simply stands for Open Data Hub. Filters starting with odh are collectively called ODHtags.

Datasets filtered with the former return all data sent by the dataset provider, while the latter returns those validated by the Open Data Hub team as well. This parameter is useful in a number of use cases. Suppose that the Open Data Hub team receives a dataset contains name and location of ski lifts within South Tyrol’s ski areas. If the dataset has not been updated in a few years, some entry in that dataset might be non valid anymore, for example a ski lift has been replaced by a cable car or has been dismantled. If this case has been verified by the Open Data Hub team, the entry referring to that ski lift will not appear in the Open Data Hub.

TT3. The seed filter

Q: What is the seed filter used for?

A: seed is used in pagination, i.e., when there are two or more pages of results, to keep the sorting across all pages. When retrieving a high number of items in a dataset it is desirable to have only a limited amount of results in each page.

It is possible to activate seed in two ways: in the dataset, choose a pagenumber (the number of the result page that will be shown first) or a pagesize (number of items in each page, we’ll use 15 in this example) and set seed to 0. At the beginning of query’s Response Body you will see something like:

 {
"TotalResults": 10564,
"TotalPages": 705,
"CurrentPage": 1,
"OnlineResults": -1,
"Seed": "43",
"Items": [
  {

The remainder of the Response Body contains the first 15 sorted items. If you now want to retrieve page 2, page 56, or any other, use 43 as seed and write 2, 56, or the desired value as pagenumber.

If you do not enter the seed, you could find an item that was already shown before, because the API can not guarantee that the same sorting is used in different queries.