Content types

For search, offers in our API are grouped into multiple databases depending on content type. This type must be included in search requests.

Depending on a content type different fields are applicable in a search query and search results may have different fields present in its results.

These content types are:

  • Pauschal: Includes hotel offers with air transport included by a tour operator.

  • Hotel: Includes only hotel offers, with customer requiring to organize their own transport.

  • Trip: Organized (and usually guided) trips performed by tour operators.

Search parameters

Search query is always sent as a single JSON object and is structured the same regardless of a search request.

All parameters are named the same in all search requests, however some are applicable only for specific content types.

Warning

If the search is not specific enough, queries may fail completly or may fail to display all results correctly. We recommend using regions query to get general pricing across regions, products to get offers in a specific set of regions and finally dates to get a list of bookable dates for a selected offer(s).

Note

By default API returns only 10 results per page. If you wish to show more results per page set Count field appropriately.

Paramater Format Description Trips Hotel Pauschal
StartDate d.m.Y / int Starting date of search period ✔️ ✔️ ✔️
EndDate d.m.Y / int Ending date of search period ✔️ ✔️ ✔️
MinDuration int Minimum duration of travel ✔️ ✔️ ✔️
MaxDuration int Maximum duration of travel ✔️ ✔️ ✔️
AdultCount int Number of adults ✔️ ✔️ ✔️
ChildrenAge array of int Age of children ✔️ ✔️ ✔️
Count int Number of results per page (default 10) ✔️ ✔️ ✔️
Page int Page number (default 0) ✔️ ✔️ ✔️
ArrivalAirport array of string* Arival airport x x ✔️
DepartureAirport array of string* Departure airport x x ✔️
TourOperator array of string* List of Tour Operator codes ✔️ ✔️ ✔️
ExcludeTourOperator array of string* List of Tour Operator codes ✔️ ✔️ ✔️
Region array of int* List of regions ✔️ ✔️ ✔️
RegionGroup array of int* List of region groups ✔️ ✔️ ✔️
Location array of int* List of locations (cities) x ✔️ ✔️
LocationName string Location name x ✔️ ✔️
GiataID array of int* List of GIATA IDs ✔️ ✔️ ✔️
RoomType array of string* List of room types x ✔️ ✔️
ServiceType array of string* List of service types (usually meal) x ✔️ ✔️
MinimumCategory int Minimum product category x ✔️ ✔️
ProductName string Explicit product name ✔️ ✔️ ✔️
ProductFacts array of string* Search GIATA Facts x ✔️ ✔️
ProductCode string Explicit product code ✔️ ✔️ ✔️
SubType string Trip subtype ✔️ ✔️ ✔️
Tags array of string Additional search tags ✔️ ✔️ ✔️
Filter Filter Requested filters ✔️ ✔️ ✔️
RFilter RFilter Range filters ✔️ ✔️ ✔️
Sort Sort Sorting by ✔️ ✔️ ✔️

StartDate and EndDate can be numeric values. If it is provided as int it is assumed that search from (today + value) days is requested. For example, StartDate = 1 and EndDate = 100 means search from tomorrow and for 100 days into the future.

If both LocationName and Location are present, LocationName is prefered.

Some fields like TourOperator, RoomTypes and similar, require specific code to be sent, representing the specific type. Please refer to Codes list. section of this documentation on where to obtain them.

Additionaly, ExcludeTourOperator takes precedence over TourOperator. For example, if TourOperator field contains values A,B,C and ExcludeTourOperator contains B,D it has the same effect as sending TourOperator with only values of A and C.

Tags are additonal values that allows you to narrow down your search to offers that only contains those values. Since those values are higly Tour Operator specific, you should consult with them as to what possible values are. Curretly only supported are users ORS SellIT.

Additionaly some modifiers are available, that take form of boolean values, that modify some search behaviour. They are send in same array as a search query.

Paramater Description Trips Hotel Pauschal
IncludeEmptyGid Include objects without GIATA ID (default=true) x ✔️ ✔️
AddTagsToName Add values of GIATA Tags to an object name ✔️ ✔️ ✔️
SearchGiataTags ProductName search field should search GIATA Tags too ✔️ ✔️ ✔️
OnlySkiResorts Search only by places that have SKI tag set ✔️ ✔️ ✔️

Refer to examples to see how this looks in practice.

* When only one element is sent it does not need to be in an array

Empty GIATA IDs

ORS Uses GIATA IDs to group objects from different data sources together and add additional information about object.

However, some data sources do not return objects with GIATA ID assigned and our system has no way of assigning it itself. In that case, we will still return object, but with GIATA ID empty. These objects usually also have less additional information available.

If you don not want to receive these objects, you can set IncludeEmptyGid search field to false. Default valuse is set to true

Filters

products and dates queries send additional data that enables you to filter the given result set. This section documents the request and response data structure.

For requesting the filter the following structure is used;

# Key in this represents the name of FilterGroup and
# value is an array of filter codes you want to filter by.
typedef Filter = map{
    string => array{string}
}

Possible filters are always returned response in Filters root key, as an following JSON structure;

typedef Filters => map{
    # Key-value pair of groups. Keys are types of
    # filters you can filter by.
    string => map{
        # Key-value pair of filters. Keys are codes you send
        # when you want to filter by given value
        string => struct{
            Value    string # User-visible value
            Selected bool   # Set to true when the filter was selected in request
                            # Otherwise this value is not displayed
        }
    }
}

Refer to example to see how this specific structure looks in practice and to specific search requests to see what kind of filters are available in each type.

Range filters

Range filters are filters that allow filtering by specific range, not just distinct values.

Range filters have the following request structure;

typedef RFilter = map{
  # Keys are types of filters you can filter by.
  string => struct{
    Minimum float
    Maximum float
  }
}

Possible filters are returned as a response in the RFilter root with the same structure as request.

Refer to example to see a more specific example.

Sorts

Sorts are returned in the Sorts key, with the following structure:

typedef Sort = array{
    map{string => string}
}

Where the key is the field name of being sorted by, and value is the direction it's sorting by (asc for ascending desc for descending).

You can request different sorting orders, by including an array of the same key-value pairs in the request. Order in which are given is important.

Refer to example to see how this works in practice.

API Quirks

The ORS API uses multiple sources to gather offers. Since some sources provide an only limited view, it can happen that with a too generic search queries you might get only a limited amount of results.

In practice, this means, that some objects will not be visible in a search unless you narrow down your search. A most common symptom of this is when an object is found by our API when you search directly by its GIATA code, but not when you search only by region this object belongs to. This tends to affect only higher-priced objects.

Example

This is an example request, including filters, sorts and range filters.

In this request, we're searching for two adults in the period anywhere from 23.11.2019 up to 23.01.2020 in region group with code 100023 (which happens to be Croatia) for 5 tour operators (given by their codes).

We also want results filtered by offers provided only by tour operators with code PALM and KOMP, by durations of only 2, 3 or 4 days. We also request price to be filtered to any offer with a price between 15 and 300 EUR.

Finally, we want the result set first sorted by GIATA ID in ascending order and then by Price in descending order.

{
  "StartDate":     "23.11.2019",
  "EndDate":       "23.01.2025",
  "AdultCount":    2,
  "RegionGroup":   100007,
  "MinDuration":   1,
  "MaxDuration":   32,
  "TourOperator":  ["PALM", "KOMP", "CEN", "SJK", "SON"],

  "Filter": {
    "Duration":     [2, 3, 4],
    "TourOperator": ["PALM", "KOMP"]
  },
  "RFilter": {
    "Price": {
      "Minmum":  15,
      "Maximum": 300
    }
  },
  "Sort": [
    {"GiataID": "asc"},
    {"Price": "desc"}
  ]
}

This is an example of communication when executing the request, including request and response HTTP headers:

# curl -H "X-Api-Key: 76e3d60e029cb8ee9b45ecd959151f35" -d '{"StartDate":"23.11.2019","EndDate":"23.01.2025","AdultCount":2,"RegionGroup":100007,"MinDuration":1,"MaxDuration":32,"Filter":{"Duration":[2,3,4],"TourOperator":["PALM","KOMP"]},"RFilter":{"Price":{"Minmum":15,"Maximum":300}},"Sort":[{"GiataID":"asc"},{"Price":"desc"}]}' https://api.ors.si/crs/v2/search/trips/products -v
> POST /crs/v2/search/trips/products HTTP/1.1
> Host: api.ors.si
> User-Agent: curl/7.66.0
> X-Api-Key: 76e3d60e029cb8ee9b45ecd959151f35
> Content-Length: 291
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 200 OK
< Date: Mon, 02 Dec 2019 11:36:06 GMT
< Server: Apache/2.4.25 (Debian)
< X-Request-ID: d17c4dcc-5de4f7265fac7652936420
< X-Requests-Left: 500
< Content-Length: 4849
< Content-Type: application/json
<

{
    "RequestID": "d17c4dcc-5e6facc17e5c7527732425",
    "Count": 140,
    "Pages": 14,
    "Page": 0,
    "Sorts": {
        "Price": "desc"
    },
    "Filters": {
        "TourOperator": {
            "KOMP": {
                "Value": "Kompas"
            },
            "OSK": {
                "Value": null
            },
            "PALM": {
                "Value": "Palma"
            },
            "SON": {
                "Value": "Son\u010dek"
            },
            "ZND": {
                "Value": "\u017dniders Turizem"
            }
        },
        "SubType": {
            "busplane": {
                "Value": "busplane"
            },
            "busplaneship": {
                "Value": "busplaneship"
            },
            "catalog": {
                "Value": "catalog"
            },
            "plane": {
                "Value": "plane"
            },
            "train": {
                "Value": "train"
            },
            "trip": {
                "Value": "trip"
            }
        },
        "Duration": {
            "1": {
                "Value": "1"
            },
            "2": {
                "Value": "2"
            },
            "3": {
                "Value": "3"
            },
            "4": {
                "Value": "4"
            },
            "5": {
                "Value": "5"
            },
            "6": {
                "Value": "6"
            },
            "7": {
                "Value": "7"
            },
            "8": {
                "Value": "8"
            },
            "9": {
                "Value": "9"
            }
        },
        "Region": {
            "100030": {
                "Value": "Trentino-S\u00fcdtirol \/ Dolomiten"
            },
            "100031": {
                "Value": "Tuscany \/ Tuscany Coast"
            },
            "100034": {
                "Value": "Abruzzo \/ Molise"
            },
            "100088": {
                "Value": "North Tyrol"
            },
            "100261": {
                "Value": "Venice & vicinity"
            },
            "100262": {
                "Value": "Roundtrips"
            },
            "100299": {
                "Value": "Italy - Around & adventure travel"
            },
            "100366": {
                "Value": "Milan and surroundings"
            },
            "99990060": {
                "Value": "Piemonte"
            },
            "99990061": {
                "Value": "Trentino-High Adige"
            },
            "99990062": {
                "Value": "Dolomites"
            }
        }
    },
    "RFilters": {
        "Price": {
            "Minimum": 32,
            "Maximum": 969
        }
    },
    "Results": [
        {
            "Product": {
                "OfferName": "Sicilija - Po poteh vulkanov",
                "GiataID": 2223491109067,
                "Picture": {
                    "Thumbnail": "https:\/\/ors.si\/giata-pics3\/2223491109067\/thumb.jpg",
                    "Full": "https:\/\/ors.si\/giata-pics3\/2223491109067\/full.jpg"
                }
            },
            "MinimumPrice": 969,
            "TourOperators": {
                "OSK": {
                    "Name": "Oskar"
                }
            },
            "ProductCodes": [
                "073BEC69-23EE-4E02-AF36-A8D90186FECC"
            ],
            "Regions": {
                "84": "Sicily"
            },
            "Durations": [
                7
            ],
            "StartDates": [
                "30-05-2020"
            ],
            "SubTypes": [
                "trip"
            ]
        },
        {
            "Product": {
                "OfferName": "APULIJA - DEZELA, KJER DISI PO PRAVI ITALIJI 4 dni",
                "GiataID": 2221540355744,
                "Picture": {
                    "Thumbnail": "https:\/\/ors.si\/giata-pics2\/2221540355744\/thumb.jpg",
                    "Full": "https:\/\/ors.si\/giata-pics2\/2221540355744\/full.jpg"
                }
            },
            "MinimumPrice": 669,
            "TourOperators": {
                "KOMP": {
                    "Name": "Kompas",
                    "Logo": "https:\/\/www.ors.si\/orslib\/ikonce\/toc\/komp.gif"
                }
            },
            "ProductCodes": [
                "10828-83360-PO_PROGRAMU"
            ],
            "Regions": {
                "78": "Apulia"
            },
            "Durations": [
                5
            ],
            "StartDates": [
                "28-04-2020",
                "26-05-2020",
                "29-09-2020",
                "27-10-2020",
                "17-11-2020"
            ],
            "SubTypes": [
                "plane"
            ]
        }
    ]
}