Completed common filter section (Tourism) #43

source/howto/tourism/getstarted.rst

@@ -52,21 +52,39 @@ 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.
+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
+<http::/tourism.opendatahub.bz.it/swagger>`_ of the API. Some examples
+of their use can be found in section :doc:`tips`.
+
+.. note:: This section is :strong:`Work in Progress` and might be
+   expanded.
+
+- :strong:`Seed` is used to set pagination. See tip :ref:`TT3
+  <tour-tt3>`.
+- :strong:`Locfilter` is a composed parameters that uniquely
+  identifies a location within South Tyrol. See example :ref:`EX2
+  <tour-ex2>` for a detailed example.
+- :strong:`Latitude` and :strong:`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
+- :strong:`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` from the nearest to the most far away from the selected
+  point.  
+- :strong:`IdFilter` allows to extract from the dataset only the items
+  with the given IDs, separated with a :literal:`,`.
+- :strong:`Active` and :strong:`OdhActive`. Filters with the same
+  name, with one prefixed by :strong:`Odh` refer to the same
+  parameter. The difference is however important: :strong:`Active`
+  indicates that the item is present in the original dataset provided,
+  while :strong:`OdhActive` shows that the item has been verified by
+  the |odh| team and is present in the |odh|. See discussion in tip
+  :ref:`TT2 <tour-tt2>`.
 
 
-.. warning:: This section is :strong:`Work in Progress` and therefore
-   incomplete!
-
-
-- :strong:`Seed` is used to set pagination. See tip :ref:`TT3 <tour-tt3>`.
-- :strong:`Active` and  :strong:`OdhActive`
-- :strong:`Locfilter`
-- :strong:`Latitude`  :strong:`Longitude`, :strong:`Radius`
-- :strong:`Geosort` Sort by Distance
-- :strong:`IdFilter` (Filter by multiple IDs)
-- :strong:`ODHTagFilter`  (Filter by ODH Tags get ODH Tags list 
-
 .. filters in each datasets
 
 Filters specific of a datasets

source/howto/tourism/tips.rst

@@ -149,33 +149,64 @@ Tips and Tricks
 filter, like in the Gastronomy dataset. Is there some equivalent
 filter?
 
-|a| Accommodations belong to a different dataset, use
-:strong:`categoryfilter` and the 
+|a| In the Accommodations dataset use :strong:`categoryfilter` instead.
 
 *****
 
 .. _tour-tt2:
 
-.. rubric:: TT2. `odhactive` and fields starting with `odh`.
+.. rubric:: TT2. `odhactive` and filter starting with `odh`.
 
-|q| What is the purpose of the `odhactive` field? And what are all
-the parameters prefixed with :strong:`odh` stand for?
+|q| What is the purpose of the `odhactive` filter? And what do all the
+filters prefixed with :strong:`odh` stand for?
 
 |a| `odh` simply stands for |odh|. There are fields like `active` and
-`odhactive`. Datasets filtered with the former return all data sent and
-validated by the dataset provider, while the latter returns those
-validated by the |odh| team as well.
+`odhactive`. Datasets filtered with the former return all data sent by
+the dataset provider, while the latter returns those validated by the
+|odh| team as well. Ths parameter is useful in a number of use
+cases. Suppose that the |odh| 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 |odh| team, the entry referring to that skilift will
+not appear in the |odh|\.
 
 
 .. _tour-tt3:
 
-.. rubric:: TT3. The `seed` field
+.. rubric:: TT3. The `seed` filter
 
-|q| What is the `seed` field used for?
+|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 same sorting in all pages. By passing to
-the API call the :literal:`null` string, no seed is generated and
-there is no sorting; by passing :literal:`0`, a seed is generated and
-will be used in pages from 2 onwards; By passing a predefined seed, it
-will be applied to all result sets.
+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
+:monospace:`pagenumber` (the number of the result page that will be
+shown first) or a :monospace:`pagesize` (number of items in each page,
+we'll use :strong:`15` in this example) and set :monospace:`seed` to
+:strong:`0`.  At the beginning of query's :strong:`Response Body` you
+will see something like:
+
+.. parsed-literal::
+
+   {
+  "TotalResults": 10564,
+  "TotalPages": 705,
+  "CurrentPage": 1,
+  "OnlineResults": -1,
+  "Seed": "43",
+  "Items": [
+    {
+    
+The remainder of the :strong:`Response Body` contains the first 15
+sorted items. If you now want to retrieve page 2, page 56, or any
+other, use :strong:`43` as :monospace:`seed` and write :strong:`2`,
+:strong:`56`, or the desired value as :monospace:`pagenumber`.
+
+If you do not enter the :strong:`seed`, you could find an item that
+was already shown before, because the API can not guarante that the
+same sorting is used in different queries.