Core - Filters

To make a reservation the User Agent must ask the user some standard data (pick-up and drop-off points and date/time) and some ad-hoc filters, that can be retrieved via this API endpoint.

The base url for the APIs in this page is at:

/api/mobile/

A JSON file with OpenAPI data about all core-related mobile APIs can be downloaded here.

Get the list of filters

GET /v1/transportation-requests/filters

Lists the filters available to fill a Transportation Request

Status Codes

200 OK – Success

The resulting object is like this:

[
  {
    "CreatedDate": "2019-05-28T11:41:26Z",                                                           // DateTime
    "LastUpdated": "2020-09-01T08:33:56Z",                                                           // DateTime
    "ValueType": 4,                                                                                  // Int
    "Key": "vg-category",                                                                            // String
    "Labels": "{\"en\":\"Category\"}",                                                               // JSON Dictionary
    "ValidValues": "["9060503a-5ba6-42b4-a01e-cbce1cb98c7e", ... ]",                                 // String Array, nullable
    "ValidValuesLabels": "{\"9060503a-5ba6-42b4-a01e-cbce1cb98c7e\":{\"en\":\"City Car\"}, ...}",    // JSON Dictionary (nullable)
    "IsRequired": true,                                                                              // Boolean
    "ID": 1                                                                                          // Int
  }
]

Implementing User Agent should parse and store locally the filters required for compiling the Transportation Requests.

The Labels property contains a JSON dictionary that must be separately parsed. In the dictionary there is the proper translation, for available IETF language tag, of the meaning of this filter.

The value of the Key property can be one of the value described in Movement Authority Filters.

The ValidValues field is a stringified array whose value, when present depending on the value of the ValueType field (see below), may vary depending on the context of the specific filter (i.e. it may be a number array, Guid array, string array…).

In the ValidValuesLabels property there is a context-dependent JSON dictionary that must be separately parsed by the User Agent. In the dictionary, for each valid value, there is the proper translation, for available IETF language tags, of the meaning of such value.

If the filter has the IsRequired property set to true, the User Agent must specify a value for the filter when compiling a Transportation Request, otherwise the submission will fail. Such value can be decided autonomously by the User Agent or can be asked to the user.

The User Agent can also hardwire some filter keys and present an autonomously defined UI, without making any use of the Labels or ValidValuesLabels properties.

Value types can be one of the AdditionalValueTypes enumeration, with the following implications:

Value	Implications
Number	In the `ValidValues` there can be a JSON array of two items, the first being the lower bound and the second being the upper bound of the allowed range. A value of null or undefined lets the end unbounded. No `ValidValuesLabels` are to be expected.
Boolean	No `ValidValues` are to be expected, but there can be `ValidValuesLabels`.
String	No `ValidValues` are to be expected, nor `ValidValuesLabels`.
Enumeration	Both `ValidValues` and `ValidValuesLabels` are to be expected, as in the example data above. The User Agent must specify exactly one of the valid values in the JSON array contained in `ValidValues` as the filter value when compiling a Transportation Request.
Multi-enumeration	Both `ValidValues` and `ValidValuesLabels` are to be expected, as in the example data above. The User Agent must specify at least one, and possibly more, of the valid values in the JSON array contained in `ValidValues` as the filter value when compiling a Transportation Request. The filter value must be a string containing a JSON array of the selected values.