Merge pull request #226 from noi-techpark/issue-220-tourism-changes

Issue 220 tourism changes

source/changelog.rst

@@ -117,3 +117,22 @@ documentation.
       The technical content of the `getting started` howtos has been
       moved to the `Datasets` section, making them
       shorter. Also a few examples have been added to :ref:`get-started-mobility`.
+
+.. changelog::
+   :version: 2021.06
+   :released: 30 June 2021
+
+   .. change::
+      :tags: Change, Improvement
+      :tickets: 220
+
+      The Tourism domain was modified and improved in several points,
+      which are reflected in the documentation:
+
+      * New Swagger and API URLs
+      * Localised methods have been definitely removed
+      * A new `extlink` to shorten URLs of tourism API in the
+        documentation source code has been introduced
+      * The :ref:`tourism-data-howto` article has been modified to
+        include the API browsable interface
+      * Tourism datasets have been ordered lexicographically

source/conf.py

@@ -73,7 +73,7 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'2021.05'
+version = u'2021.06'
 # The full version, including alpha/beta/rc tags.
 release = version
 
@@ -111,7 +111,9 @@
 
 extlinks = { 'sasabus': ('http://sasabus.org/%s', None),
              'stinfo':
-             ('http://tourism.opendatahub.bz.it/swagger/ui/index#%s', None)
+             ('https://tourism.api.opendatahub.bz.it/#%s', None),
+             'apit':
+             ('https://tourism.api.opendatahub.bz.it/v1%s', None)
 }
 
 numfig = True

source/datasets.rst

@@ -336,6 +336,9 @@ for e-cars.
 Datasets in the Tourism Domain
 ------------------------------
 
+.. versionchanged:: 2021.06 modified URLs of datasets and API; ordered
+   Tourism datasets lexicographically
+
 .. toctree::
    :hidden:
 
@@ -357,7 +360,6 @@ find information about winter and summer offers from local touristic
 boards, information about weather, hotels and accommodation, Points of
 Interests, and a lot more.
 
-
 The following information is provided for each dataset in the Tourism domain:
 
 .. csv-table::
@@ -392,42 +394,18 @@ The following information is provided for each dataset in the Tourism domain:
 
     Other howtos are available in the :ref:`dedicated section <howto-list>`.
 
-.. _package-dataset:
+.. _accommodation-dataset:
 
-:link-badge:`package-dataset,it.bz.opendatahub.package,ref,badge-light`
+:link-badge:`accommodation-dataset,it.bz.opendatahub.accommodation,ref,badge-light`
 
-.. include:: /datasets/package.rst
+.. include:: /datasets/accommodation.rst
 
 .. _activity-dataset:
 
 :link-badge:`activity-dataset,it.bz.opendatahub.activity,ref,badge-light`
 
 .. include:: /datasets/activity.rst
 
-.. _event-dataset:
-
-:link-badge:`event-dataset,it.bz.opendatahub.event,ref,badge-light`
-
-.. include:: /datasets/event.rst
-
-.. _gastronomy-dataset:
-
-:link-badge:`gastronomy-dataset,it.bz.opendatahub.gastronomy,ref,badge-light`
-
-.. include:: /datasets/gastronomy.rst
-
-.. _poi-dataset:
-
-:link-badge:`poi-dataset,it.bz.opendatahub.poi,ref,badge-light`
-
-.. include:: /datasets/poi.rst
-
-.. _accommodation-dataset:
-
-:link-badge:`accommodation-dataset,it.bz.opendatahub.accommodation,ref,badge-light`
-
-.. include:: /datasets/accommodation.rst
-
 .. _activity_poi-dataset:
 
 :link-badge:`activity_poi-dataset,it.bz.opendatahub.activity_poi,ref,badge-light`
@@ -440,18 +418,42 @@ The following information is provided for each dataset in the Tourism domain:
 
 .. include:: /datasets/common.rst
 
+.. _event-dataset:
+
+:link-badge:`event-dataset,it.bz.opendatahub.event,ref,badge-light`
+
+.. include:: /datasets/event.rst
+
 .. _eventshort-dataset:
 
 :link-badge:`eventshort-dataset,it.bz.opendatahub.eventshort,ref,badge-light`
 
 .. include:: /datasets/eventshort.rst
 
+.. _gastronomy-dataset:
+
+:link-badge:`gastronomy-dataset,it.bz.opendatahub.gastronomy,ref,badge-light`
+
+.. include:: /datasets/gastronomy.rst
+
 .. _location-dataset:
 
 :link-badge:`location-dataset,it.bz.opendatahub.location,ref,badge-light`
 
 .. include:: /datasets/location.rst
 
+.. _package-dataset:
+
+:link-badge:`package-dataset,it.bz.opendatahub.package,ref,badge-light`
+
+.. include:: /datasets/package.rst
+
+.. _poi-dataset:
+
+:link-badge:`poi-dataset,it.bz.opendatahub.poi,ref,badge-light`
+
+.. include:: /datasets/poi.rst
+
 .. _ski-dataset:
 
 :link-badge:`ski-dataset,it.bz.opendatahub.ski,ref,badge-light`

source/datasets/accommodation.rst

@@ -20,7 +20,7 @@
       "API version", "v1, AlpineBits HotelData 2017-10, 2018-10, and soon
       2020-10"
       "Swagger URL", ":stinfo:`/Accommodation`"
-      "API URL", "http://tourism.opendatahub.bz.it/api/Accommodation"
+      "API URL", ":apit:`/Accommodation`"
       "Use cases and info", "https://databrowser.opendatahub.bz.it/
       https://suedtirol.info/"
       "Android App", "`Südtirol Guide/Alto Adige Guide

source/datasets/activity.rst

@@ -19,7 +19,7 @@
       "E-mail contact", "|contact|"
       "API version", "v1"
       "Swagger URL", ":stinfo:`/Activity`"
-      "API URL", "http://tourism.opendatahub.bz.it/api/Activity"
+      "API URL", ":apit:`/Activity`"
       "Use cases and info", "https://databrowser.opendatahub.bz.it/
       https://suedtirol.info/"
       "Sources", "LTS ActivityData"

source/datasets/activity_poi.rst

@@ -28,8 +28,8 @@
       "Output", "JSON, mime-type application/json"
       "E-mail contact", "|contact|"
       "API version", "v1"
-      "Swagger URL", ":stinfo:`/ODHactivityPoi`"
-      "API URL", "http://tourism.opendatahub.bz.it/api/ODHActivityPoi"
+      "Swagger URL", ":stinfo:`/ODHActivityPoi`"
+      "API URL", ":apit:`/ODHActivityPoi`"
       "Use cases and info", "https://databrowser.opendatahub.bz.it/
       https://suedtirol.info/"
       "Android App", "`Südtirol Guide/Alto Adige Guide

source/datasets/event.rst

@@ -18,7 +18,7 @@
       "E-mail contact", "|contact|"
       "API version", "v1"
       "Swagger URL", ":stinfo:`/Event`"
-      "API URL", "http://tourism.opendatahub.bz.it/api/Event"
+      "API URL", ":apit:`/Event`"
       "Use cases and info", "https://databrowser.opendatahub.bz.it/
       https://suedtirol.info/"
       "Android App", "`Südtirol Guide/Alto Adige Guide

source/datasets/eventshort.rst

@@ -18,7 +18,7 @@
       "E-mail contact", "|contact|"
       "API version", "v1"
       "Swagger URL", ":stinfo:`/EventShort`"
-      "API URL", "http://tourism.opendatahub.bz.it/api/EventShort"
+      "API URL", ":apit:`/EventShort`"
       "Use cases and info", "https://today.noi.bz.it/
       https://noi.bz.it/event-calendar/
       https://virtual.noi.bz.it/programma.html"

source/datasets/gastronomy.rst

@@ -19,7 +19,7 @@
       "E-mail contact", "|contact|"
       "API version", "v1"
       "Swagger URL", ":stinfo:`/Gastronomy`"
-      "API URL", "http://tourism.opendatahub.bz.it/api/Gastyronomy"
+      "API URL", ":apit:`/Gastyronomy`"
       "Use cases and info", "https://databrowser.opendatahub.bz.it/
       https://suedtirol.info/"
       "Sources", "LTS"

source/datasets/location.rst

@@ -12,4 +12,4 @@
       "E-mail contact", "|contact|"
       "API version", "v1"
       "Swagger URL", ":stinfo:`/Location`"
-      "API URL", "http://tourism.opendatahub.bz.it/api/Location"
+      "API URL", ":apit:`/Location`"

source/datasets/poi.rst

@@ -19,7 +19,7 @@
       "E-mail contact", "|contact|"
       "API version", "v1"
       "Swagger URL", ":stinfo:`/Poi`"
-      "API URL", "http://tourism.opendatahub.bz.it/api/Poi"
+      "API URL", ":apit:`/Poi`"
       "Use cases and info", "https://databrowser.opendatahub.bz.it/
       https://suedtirol.info/"
       "Sources", "LTS PoiData"

source/datasets/ski.rst

@@ -12,5 +12,5 @@
       "Output", "JSON, mime-type application/json"
       "E-mail contact", "|contact|"
       "API version", "v1"
-      "Swagger URL", ":stinfo:`!/Common/Common_GetSkiAreas`"
-      "API URL", "http://tourism.opendatahub.bz.it/api/SkiArea"
+      "Swagger URL", ":stinfo:`!/Common/get_v1_SkiArea`"
+      "API URL", ":apit:`/SkiArea`"

source/datasets/snowreport.rst

@@ -20,8 +20,8 @@
       "Output", "JSON, mime-type application/json"
       "E-mail contact", "|contact|"
       "API version", "v1"
-      "Swagger URL", ":stinfo:`/Weather/Weather_GetSnowReportBase`"
-      "API URL", "http://tourism.opendatahub.bz.it/api/Weather/SnowReportBase"
+      "Swagger URL", ":stinfo:`/Weather/get_v1_Weather_SnowReport`"
+      "API URL", ":apit:`/Weather/SnowReportBase`"
       "Use cases and info", "https://databrowser.opendatahub.bz.it/
       https://suedtirol.info/"
       "Sources", "LTS, IDM"

source/datasets/venue.rst

@@ -19,6 +19,6 @@
       "E-mail contact", "|contact|"
       "API version", "v1"
       "Swagger URL", ":stinfo:`/Venue`"
-      "API URL", "http://tourism.opendatahub.bz.it/api/Venue"
+      "API URL", ":apit:`/Venue`"
       "Use cases and info", "https://databrowser.opendatahub.bz.it/"
       "Sources", "LTS"

source/datasets/webcam.rst

@@ -17,7 +17,7 @@
       "E-mail contact", "|contact|"
       "API version", "v1"
       "Swagger URL", ":stinfo:`/WebcamInfo`"
-      "API URL", "http://tourism.opendatahub.bz.it/api/WebcamInfo"
+      "API URL", ":apit:`/WebcamInfo`"
       "Use cases and info", "https://databrowser.opendatahub.bz.it/
       https://suedtirol.info/"
       "Sources", "Webcam links from LTS and IDM"

source/howto/tourism/getstarted.rst

@@ -5,27 +5,37 @@ How to access Tourism Data?
 ===========================
 
 .. versionchanged:: 2021.05 moved technical info to dataset section
+
+.. versionchanged:: 2021.06 removed broken URL, added `browsing API`
+   section, general improvement to the content
 
-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.
+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 :ref:`tourism-tech`.
 
-.. _data-access-tourismAPI:
 
-Data Access and Manipulation
-----------------------------
+Swagger Interface
+-----------------
 
 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
+
+https://tourism.api.opendatahub.bz.it/
+
+.. hint:: Check section :ref:`tourism-datasets` 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.
 
+.. _data-access-tourismAPI:
+
+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 :strong:`Authorize` button on the right-hand side of the page
@@ -69,8 +79,37 @@ data.
 To log out, click again on :strong:`Authorize` in the Swagger UI (see
 :numref:`tourism-ui`), then on :strong:`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.
+
+.. _tourism-api-browse:
+
+.. figure:: /images/API-browser.png
+   :scale: 33%
+   :align: center
+
+   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
+:numref:`tourism-api-browse` 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
 :command:`curl` or :command:`wget`, or only from scripts, you need to
@@ -95,5 +134,3 @@ One you have retrieved the data, which come in JSON format, you can
 process and manipulate them with a tool like `jq
 <https://github.com/stedolan/jq>`_.
 
-.. seealso:: More detailed documentation of the exposed API methods
-   can be found on http://tourism.opendatahub.bz.it/Help.

source/tourism-tech.rst

@@ -25,6 +25,9 @@ manifold:
 Structure of the API calls
 ==========================
 
+.. versionchanged:: 2021.06 marked as unavailable two API calls that
+   were removed 
+
 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
@@ -50,16 +53,16 @@ The calls defined for every datasets are:
   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
+The following calls have been :strong:`removed` 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
-:ref:`fields-filter` and is
-described in section :ref:`language-filter`.
+:ref:`fields-filter` and is described in section
+:ref:`language-filter`.
 
-- :literal:`/api/{Name}Localized` Return the whole dataset in only
-  the given language (which is a mandatory part of the query). 
-- :literal:`/api/{Name}Localized/{Id}` Return only item with given Id
-  an in given language.
+- :strike:`/api/{Name}Localized Return the whole dataset in only
+  the given language (which is a mandatory part of the query)`
+- :strike:`/api/{Name}Localized/{Id} Return only item with given Id
+  an in given language.`
 
 .. _common-filters: