Accessing the Open Data Hub

Changed in version 2021.08: move ODH Virtual Knowledge Graph subsection from Dataset section

There are different modalities to access data that are provided by the Open Data Hub, that are listed here. Currently, data from the Mobility and Tourism domains can be accessed, both from the command line and using a browser. Non-interactive access using APIs is also available. Various dedicated tutorials are available in the List of HOWTOs section; while in section Getting Involved you can find additional ways to interact with the data and the Open Data Hub team. The remainder of this section describes all the possibilities to access the Open Data Hub’s datasets and their content.

Browser access

Accessing data in the Open Data Hub by using a browser is useful on different levels: for the casual user, who can have a look at the type and quality of data provided; for a developer, that can use the REST API implemented by the Open Data Hub or even check if the results of his app are coherent with those retrieved with the API; for everyone in order to get acquainted with the various methods to retrieve data.

More in detail, these are the possibilities to interact with Open Data Hub’s data by using a browser:

Go to the Apps Built From Open Data Hub Datasets section of the documentation, particularly sub-sections Production Stage Apps and Beta Stage Apps, and choose one of the web sites and portals that are listed there. Each of them uses the data gathered from one or more OPEN DATA HUB’s datasets to display a number of useful information. You can then see how data are exposed and browse them.

In the same Apps Built From Open Data Hub Datasets section, you can also check the list of the Alpha Stage Apps and choose one of them that you think you can expand, then get in touch with the authors to suggest additional features or collaborate with them to discuss its further development to improve it.

Access the ODH Tourism data browser and search for the Open Data available in the Tourism domain. You can simply use those data for your convenience, or you might even find a novel way to exploit those data and use them in an app or portal you are going to develop. A detailed howto is available: How to use the Open Data Hub’s Tourism Data Browser? to help you getting acquainted with the browser.

Go to the Swagger interface of the datasets in the Tourism domain, located at https://tourism.opendatahub.bz.it/swagger/ui/index to learn how the REST APIs are built and how you can script them to fetch data for your application. To get started, there is a dedicated howto: How to access Tourism Data? that will guide you in the first steps.

Access the Swagger interface of the datasets in the Mobility domain, located at https://mobility.api.opendatahub.bz.it/. Like in the case of the tourism’ Swagger interface, you can learn REST API call for that domain and fetch data for your application. More possibilities to interact with the Mobility domain datasets and the description of the new APIv2 are described in the dedicated howto.

Open the Analytics for Mobility web page, at https://analytics.opendatahub.bz.it/ This portal uses data in the mobility domain to display various information about the sensors, including their locations, what they measure, and actual data in near-real time. You can retrieve data gathered by the sensors directly from the dataset, in almost real-time.

Open the Open Data Hub Knowledge Graph Portal where you can explore all the data that are already available as a virtual knowledge graph. Here you can check out some of the precooked query to see and modify them to suit your needs with the help of W3C’s SPARQL query language; SPARQL can be used also in the Playground to freely query the endpoint.

Programmatic access

Programmatic and non-interactive access to the Open Data Hub’s dataset is possible using any of the following methods made available by the Open Data Hub team.

AlpineBits client

The AlpineBits Alliance strives to develop and to spread a standard format to exchange tourism data. Open Data Hub allows access to all data produced by AlpineBits using dedicated endpoints:

The AlpineBits HotelData dataset can be access from https://alpinebits.opendatahub.bz.it/AlpineBits/.

The AlpineBits DestinationData endpoint is available at https://destinationdata.alpinebits.opendatahub.bz.it/.

Statistical Access with R

R is a free software for statistical analysis that creates also graphics from the gathered data.

The Open Data Hub Team has developed and made available bzar, an R package that can be used to access BZ Analytics data (see also How to Access Analytics Data in the Mobility Domain) and process them using all the R capabilities. Download and installation instructions, along with example usage can be found on the bzar repository.

See also

There is a howto that explains how to fetch data from the Open Data Hub datasets using R and SPARQL: How to Access Open Data Hub Data With R and SPARQL.

API

The APIs are composed of a few generic methods, that can be combined with many parameters to retrieve only the relevant data and then post-processed in the preferred way.

The following table summarises how the two versions of the API can be used within the Open Data Hub’s domains.

API

Tourism

Mobility

v1

recommended

deprecated

v2

recommended

There are currently two versions of the API, v1 and v2, with the former now deprecated for the Mobility domain and marked as such deprecated throughout the Open Data Hub documentation. New users are recommended to use the new API v2, while users of the API v1 are encouraged to plan a migration to the new API.

The new API v2 has a different approach compared to the previous version, and therefore is not compatible with the API v1, the main difference being that all data stored in the Open Data Hub can now be retrieved from a single endpoint, while with API v1 there was an endpoint for each dataset.

This change in approach requires also a breaking change for the users of API v1. The initial step, indeed, will not be to open the URL of the dataset and start exploring, but to retrieve the stationTypes and then retrieve additional data about each station. A stationType is the main object of a datasets, about which all the information in a dataset relate to; a dataset includes at least one stationType. A new, dedicated howto describing in detail the new API v2 and a few basic examples is already available in the dedicated section of this documentation.

Note

It is important to remark that the API v2 is only available for datasets in the Mobility Domain.

CLI access

Unlike browser access, that provides an interactive access to data, with the option to incrementally refine a query, command line access proves useful for non-interactive, one-directional, and quick data retrieval in a number of scenarios, including:

  • Scripting, data manipulation and interpolation, to be used in statistical analysis.

  • Applications that gather data and present them to the end users.

  • Automatic updates to third-parties websites or kiosk-systems like e.g., in the hall of hotels.

Command line access to the data is usually carried out with the curl Linux utility, which is used to retrieve information in a non-interactive way from a remote site and can be used with a variety of options and can save the contents it downloads, which can them be send to other applications and manipulated.

The number of options required by curl to retrieve data from Open Data Hub’s dataset is limited, usually they are not more than 3 or 4, but their syntax and content might become long and not easily readable by a human, due to the number of filters available. For example, to retrieve the list of all points of interests in South Tyrol, the following command should be used:

~$ curl -X GET "https://tourism.api.opendatahub.bz.it/v1/ODHActivityPoi?pagenumber=1&pagesize=10&type=63&subtype=null&poitype=null&idlist=null&locfilter=null&langfilter=null&areafilter=null&highlight=null&source=null&odhtagfilter=null&odhactive=null&active=null&seed=null&latitude=null&longitude=null&radius=null" -H "accept: application/json"

Your best opportunity to learn about the correct syntax and parameters to use is to go to the swagger interface of the tourism or mobility domains and execute a query: with the output, also the corresponding curl command used to retrieve the data will be shown.

The Open Data Hub Virtual Knowledge Graph

New in version 2021.02: Description of the Knowledge Model underlying datasets Accommodation, Gastronomy, and Event

New in version 2021.06: Description of the Knowledge Model underlying the mobility domain

Some datasets in the Open Data Hub, namely Accommodation, Gastronomy, and Event, are organised into a Virtual Knowledge Graph that can be accessed using SPARQL from the dedicated SPARQL endpoint. In order to define more precise queries, this section describes the Knowledge Models (KM) underlying these datasets; the description of each KM is accompanied by an UML diagram which shows the KM at a glance.

Besides standard W3C’s OWL and RDF vocabularies, the Open Data Hub VKG uses:

Common Notation

Diagrams use UML class diagram formalism widely adopted in Knowledge Representation and in particular in the W3C’s Recommendation documents for the Semantic Web. The following additional notation applies:

Prefix

The default prefix used for classes and properties is https://schema.org/. This means that, unless differently stated, the definition of classes and properties, including their attributes, rely on a common standard as defined in schema.org’s vocabulary. As examples, see the LodgingBusiness class and the containedInPlace property.

Hint

Other prefixes are explicitly pre-pended to the Class or Property name, like e.g., noi:numberOfUnits.

Arrows

Arrows with a white tip denote a sub-class relationship, while black tips denote object properties.

Cardinality

Cardinality of 1 is usually not shown, but implied; the look across notation is used. For example, the image on the right-hand side–excerpt from the event dataset VKG–can be read as 0 to N MeetingRooms are ContainedInPlace Place.

background image
Mobility Domain

The entire mobility domain has a unique underlying knowledge model, which encompasses all the datasets and therefore also allows an easier creation of cross-dataset queries. Since the mobility domain gathers data from sensors, useful in this domain is also the SOSA ontology, which uses sosa as prefix. You can check the Classes and Properties of SOSA in the W3C’s dedicated wiki page

The central concept is Station, of which all StationTypes are subclass, while Observation, LatestObservation, and ObservableProperty are used to provide time-related information of the data gathered and relate to Sensor. Together with Platform, Sensor make the relation between a Station and its Sensors: For example, sensor EChargingPlug isHostedby an EChargingstation Platform, which is also a Station.

The knowledge model is completed by the Feature superconcept, which contains also Municipality and RoadSegment, the latter defined by an hasOriginStation and an hasDestinationStation.

_images/odh-mobility.png

Figure 4 The UML diagram of the Mobility Domain.

Accommodation Dataset

Central class in this dataset is LodgingBusiness, to which belong multiple Accommodations.

A LodgingBusiness has as attributes geo:asWKT, email, name, telephone, and faxNumber and relations

  • address to class PostalAddress, which consists of streetAddress, postalCode, and AddressLocality

  • geo, i.e., a geographical location, to class GeoCoordinates, consisting of latitude, longitude, and elevation

There are (sub-)types of LodgingBusiness–called Campground, Hotel, Hostel, and BedAndBreakfast–sharing its attributes and relations.

An Accommodation is identified by a name and a noi:numberOfUnits and has relations

  • containedInPlace to LodgingBusiness (multiple Accommodations can belong to it)

  • occupancy to QuantitativeValue, which gives the maxValue and minValues of available units of accommodation and a unitCode.

_images/odh-accommodation.png

Figure 5 The UML diagram of the Accommodation Dataset.

Gastronomy Dataset

The main class of this dataset is FoodEstablishment, described by geo:asWKT, description, name, telephone, and url.

A FoodEstablishment has

  • a PostalAddress–consisting of streetAddress, postalCode, and AddressLocality–as address

  • a GeoCoordinateslatitude, longitude, and elevation–as a geographical location geo

There are different (sub-)types of FoodEstablishment, all sharing the same attributes: Restaurant, FastFoodRestaurant, BarOrPub, Winery, and IceCreamShop.

_images/odh-food-establishment.png

Figure 6 The UML diagram of the Gastronomy Dataset.

Event Dataset

The main classe in this dataset is Event, described by a startDate, an endDate, and a description. Every Event has an organizer, either a Person or an Organization and a location.

A Person–identified by givenName, familyName, email, and telephoneworksFor an Organization, which has a name and an address, i.e., a PostalAddress consisting of streetAddress, postalCode, AddressLocality, and AddressCountry.

Finally, an Event has as location a MeetingRoom–identified by a name– which is containedInPlace a Place–which has also a name

_images/odh-event.png

Figure 7 The UML diagram of the Event Dataset.

See also

The SPARQL howto, which guides you in interacting with the SPARQL endpoint.

W3C Recommendation for OWL2 and RDF.

Official Specification of UML Infrastructure are available from Object management group

The AlpineBits Client

_images/alpinebits-logo.png

New in version 2021.09: Dedicated section for AlpineBits.

The AlpineBits Alliance strives to develop and to spread a standard format to exchange tourism data. There are two datasets they developed and keep up to date, that are of particular interest for Open Data Hub users: HotelData and DestinationData.

DestinationData

The AlpineBits DestinationData is a standardisation effort to allow the exchange of information related to mountains, events, tourism. Developed by the AlpineBits Alliance, Destination Data relies on a number of standards (Including json, REST API, Schema.org, OntoUML to build the AlpineBits DestinationData Ontology, the core result of the effort. The goal of DestinationData it to provide a means to describe events, their location, and additional information on them. For this purpose, the DestinationData Ontology specifies a number of Named Entities used to describe Events and Event Series, Mountain Areas, Places, Trails, Agents, and so on.

The full specification of the ontology, including architecture of the API and description of the datatypes defines can be found in the latest 2021-04 version of the official Destination Data specs (pdf ).

The reference implementation of AlpineBits DestinationData is provided by Open Data Hub and publicly available at the dedicated endpoint at https://destinationdata.alpinebits.opendatahub.bz.it/.

See also

More information and resources about AlpineBits DestinationData can be found on the official page.

HotelData

The AlpineBits HotelData is meant for data strictly related to hotels and booking, like Inventory Basic, Inventory HotelInfo, and FreeRooms. This dataset can be access from the dedicated endpoint at https://alpinebits.opendatahub.bz.it/AlpineBits/

See also

The dedicated howto How to access Open Data Hub AlpineBits Server as a client.

The official page of AlpineBits HotelData.