Accommodation Workflow - noi-techpark/opendatahub-docs GitHub Wiki

The complete Accommodation data

  • all properties for Accommodation base data
  • rooms from sources LTS and HGV,
  • full Imagegallery with all Images
  • Availablity Search funtionality

is only returned when a valid Token with the right permission is passed to the Open Data Hub.

Accommodation Base data (static information)

The Accommodation Base data is retrieved from LTS TIC Web.
TIC Web helds also the information which ID the Accommodation has on the HGV System.
Not every Accommodation is available on the HGV System. At the moment whe have approximately 10.000 Accommodations on the LTS System and 2500 available also on the HGV System.
"A0RID": "b99e6e565478234782adfsdsfa150b0b" is the LTS ID
"HGVId": "12488", is the HGV ID
The Accommodation Base data does NOT include any pricing information.
On Accommodation Base data all rooms that are available are listed in the section AccoRoomInfo with the information where this data comes from
example:

AccoRoomInfo: [
{
Id: "30BA97D92CEDF6E641ASDF3E626",
Self: "https://tourism.opendatahub.bz.it/v1/AccommodationRoom/30BA97D92CEDF6E641ASDF3E626",
Source: "lts"
}]

Accommodation Room data (static information)

The Accommodation room data is retrieved from LTS TIC Web.
For each Accommodation that is available on HGV also the room data of Source HGV is added to ODH.

ODH lets is up to the data consumer to decide which room data should be used.

The room data of an Accommodation between this two sources can differ.
Rooms from source "hgv" have a static Price information for example "PriceFrom": 75 which is helpful to give an indication what the price range is.
Rooms from source "lts" does NOT have this price information.
To avoid confusion we recommend this strategy: Use rooms from source HGV for each Accommodation available on the HGV System, otherwise use rooms of source LTS.

Availability Search

The Availablility Search Result can be requested with or without accommodation base data. When the Availability Search is requested with the accommodation base data the result is wrapped in the Object MssResponseShort.
A empty object means there is no availability for this Accommodation.
In General an Availability Search can be done with a low detail grade detail=0 (for displaying an availablity search result on a list) or high detail grade detail=1 (which returns detailed room informations like descriptions and images).

There are more possibilities to get the availability of the Accommodations:

  • using the /v1/Accommodation (GET) Endpoint (List). Use the filters offered by this endpoint and get the Availability from HGV/LTS (with base data)
  • using the /v1/Accommodation/{id} (GET) Endpoint (Single) get the Availability from HGV/LTS for a single Accommodation (with base data)
  • using the /v1/AccommodationAvailable (POST) Pass the Ids of the Accommodations to check and get Accommodation Base data with the Availability from HGV/LTS ( (with/without base data))

The recommended Endpoint for an Availability check is /v1/AccommodationAvailable (POST) it contains the full features, on the standard Accommodation Endpoint the availabilitysearch can be seen as extension.

Parameters of the Availability Search

  • availabilitycheck Enable the Availabilitycheck (only for Endpoints Accommodation)
  • arrival Departure DATE (yyyy-MM-dd)
  • departure Arrival DATE (yyyy-MM-dd)
  • boardfilter Boardfilter (values: 0 = (all boards), 1 = (without board), 2 = (breakfast), 4 = (half board), 8 = (full board), 16 = (All inclusive), 'null' = No Filter all Boarding options are requested)
  • roominfo Roominfo Filter (Splitter for Rooms '|' Splitter for Persons Ages ',') (Room Types: 0=notprovided, 1=room, 2=apartment, 4=pitch/tent(onlyLTS), 8=dorm(onlyLTS)) possible Values Example 1-18,10|1-18 = 2 Rooms, Room 1 for 2 person Age 18 and Age 10, Room 2 for 1 Person Age 18), (default:'1-18,18') Default value : 1-18,18
  • bokfilter Booking Channels Filter (Separator ',' possible values: hgv = (Booking Südtirol), lts = (LTS Availability check))
  • detail Detail of the Availablity check (string, 1 = full Details, 0 = basic Details (default))
  • availabilitychecklanguage Language of the Availability response
  • locfilter Use the Locfilter to prefilter Accommodations
  • availabilityonly (only available in Endpoint AccommodationAvailable) true = Shows only the Availability Search result without Accommodation Base data
  • usemsscache (only available in Endpoint AccommodationAvailable) The MSS offers the possibility to get the Availability Result for all Accommodations, this request is potentially cached by the MSS. By using usemsscache = true the request is done on all Accommodations of South Tyrol. If a location filter or some Ids are passed to the api, the resultset of the MSS is filtered against this parameters. If no filters are passed the plain MSS resultset is returned.
  • uselcscache (only available in Endpoint AccommodationAvailable) Currently not available
  • removeduplicatesfrom (only available in Endpoint AccommodationAvailable) If this option is set (possible values hgv,lts) the offers from the selected source is hidden, if on the other source there exists a valid offer.
  • msssource Pass to the HGV interface the Requestor Source (here for compatibility reasons)

In the AccommodationAvailable Endpoint the Accommodation Ids are passed as POST Body Example "EA615C5794E011D2B48C00407899786,32E7B9548E7B78781AB006097B896BA"

Availability Search HGV (MSS)

An Availability Search on the HGV System produces a Response where all online bookable (on Booking Southtyrol) Accommodations are listed. All available Accommodations in the requested period on the HGV System are returned and can be booked online. An availability search can be done The Response includes (with detail:1)

  • room prices
  • room quantity
  • descriptions
  • room images
  • valid room combinations (if more rooms are requested, with consideration the available room quantity)

Availability Search LTS (LCS)

An Availability Search on the LTS System produces a Response where all available Accommodations on the LTS System in the requested period are included. This means the Accommodation is available on request (Inquiry, or by contacting the Accommodation). The Response includes (with detail:1)

  • room prices
  • room quantity
  • descriptions
  • valid room combinations (if more rooms are requested, with consideration the available room quantity)

Note: In difference to HGV Availability Check the LTS Service is NOT returning Room Images. The Room Images of the base room data has to be used.

An Accommodation can be available on the HGV and LTS System with different prices, the overall strategy is online bookability over availability on request.

How LTS and HGV is syncing information

The TIC Web and the HGV System is usually in sync. However it can occur some data mismatch.

Performance of the Availability Search

The Performance of the availability search depends from the response times of the provider HGV & LTS.
General Recommendations:
Avoid performing Availability Searches over all Accommodations, especially the LTS System (has 10k Accommodations to check) takes a lot of time. The HGV System in this case produces better results because it makes use of a Cache (by passing parameter without usemsscache=true) but consider that it has a significantly lower amount of Accommodations to check.
Use Caching where it is possible.
Reduce the amount of Accommodations to check.
Request only what you are able to show as result (Example when a certain amount of Accommodations is requested and the probability of getting over 20 Online Bookable Results is high do not request LTS Availability)

The AccommodationAvailable Endpoint (POST)

Passing IDs in the Body

MSS (HGV)

The Ids are directly passed to MSS and the Plain Resultset is returned. If usemsscache=true is used the MSS Resultset over all Accommodations (which is potentially cached) is used and the resultset is filtered by the passed IDs. If a very high number of IDs (>2500) is requested, the use of the cache may speed up the query.
If no parameter usemsscache is provided, the query is done without the usage of MSS Caching.

LCS (LTS)

The Ids are directly passed to LCS and the Plain Resultset is returned. The parameter uselcscache=true has no affections in this modality.

Using the Locfilter

MSS (HGV)

Opendatahub queries the DB and filters by the given location filter (By default, publisher idm-marketplace, only active accommodations and only bookable Accommodations are filtered) then all Ids are directly passed to MSS and the Plain Resultset is returned. If usemsscache=true is used the MSS Resultset over all Accommodations (which is potentially cached) is used and the resultset is filtered by the result of the IDs with the given location filter. If a very high number of IDs (>2500) is requested, the use of the cache may speed up the query.
Since Open Data Hub does not know about the amount of IDs the query produced and no parameter usemsscache is provided, the query is done without the usage of MSS Caching.

LCS (LTS)

Opendatahub queries the DB and filters by the given location filter (By default, publisher idm-marketplace and only active accommodations are filtered) then all Ids are directly passed to LCS and the Plain Resultset is returned. The parameter uselcscache=true has no affections in this modality.

Search over all Accommodations

MSS (HGV)

If usemsscache=false is used, Opendatahub uses a cached Bookable Ids Resultset (By default is is filtered by publisher idm-marketplace, only active and only bookable Accommodations), all Ids are directly passed to MSS and the Plain Resultset is returned.
If usemsscache=true is used no IDs are loaded the MSS Resultset over all Accommodations (which is potentially cached) is used and the resultset is plain returned. In this case the response can also contain not active / not publishedon idm-marketplace or even unknown Accommodation IDs and has to be checked on client side. The best performance if a search is done over all Accommodations is by using this MSS Caching mechanism. If no parameter usemsscacheis passed Open Data Hub** in this case uses the cached MSS Strategy**.

LCS (LTS)

Opendatahub uses a cached Ids Resultset (By default is is filtered by publisher idm-marketplace, only active Accommodations), all Ids are directly passed to LCS and the Plain Resultset is returned.
If uselcscache=true is used no IDs are loaded and passed to the LCS, so the LCS Resultset over all Accommodations (which is potentially cached) is used and the resultset is plain returned. In this case the response can also contain not active / not publishedon idm-marketplace and has to be checked on client side. The best performance if a search is done over all Accommodations is by using this LCS Caching mechanism.

Recap Caching Features of MSS and LCS

MSS

Caching is only available if the request is done over all Accommodations. If a similar Request was done in a certain time period before, The request is served by the MSS Cache and the response time is significantely lower.

Request over all Accommodations

bokfilter type cache parameter test1 test2 test3 test4 test5 test6 median strategy
mss without ids null 2,67 0,987 0,933 0,885 1,02 1,01 0,9985 mss caching used
mss without ids cache false 2,54 2,62 2,5 2,56 2,63 2,53 2,55 mss caching disabled
mss without ids cache true 2,51 0,925 0,976 0,979 0,978 0,953 0,977 mss caching used

Request with a Locationfilter of about 3300 Accommodations

bokfilter type cache parameter test1 test2 test3 test4 test5 test6 median strategy
mss 3260 ids null 2,19 1,96 1,84 1,85 1,92 2,01 1,94 mss caching NOT used
mss locfilter (more regs 3260) cache false 1,88 1,89 1,95 2,08 1,99 2,03 1,97 mss caching disabled
mss locfilter (more regs 3260) cache true 1,61 1,45 1,28 1,38 1,3 1,32 1,35 mss caching used

Request with passed 1000 Ids

bokfilter type cache parameter test1 test2 test3 test4 test5 test6 median strategy
mss locfilter (Gröden 1150) cache null 1,32 1,43 1,24 1,29 1,29 1,27 1,29 mss caching NOT used
mss locfilter (Gröden 1150) cache false 1,39 1,29 1,22 1,31 1,33 1,33 1,32 mss caching disabled
mss locfilter (Gröden 1150) cache true 1,06 1,14 1,05 0,992 0,995 1,06 1,055 mss caching used

Request with passed 100 Ids

bokfilter type cache parameter test1 test2 test3 test4 test5 test6 median strategy
mss idlist (100 random) null 0,442 0,37 0,312 0,358 0,34 0,325 0,349 mss caching NOT used
mss idlist (100 random) cache false 0,4 0,36 0,305 0,395 0,302 0,322 0,341 mss caching disabled
mss idlist (100 random) cache true 2,41 0,774 0,784 0,793 0,922 0,784 0,7885 mss caching used

LCS

LCS offers caching by default. If the same request is done in a certain time period the response is served by the LCS Cache, and therefore has a faster response time. LCS offers the possibility to do a request without passing Accommodation IDs, in this case LCS checks all Accommodations in South Tyrol. So the parameter "uselcscache=true" has only sense when using it on an Availability check over the whole Accommodations, at the moment all it does is to omit the Accommodation IDs loading and filling the IDs into the request.

No significant performance optimizations noticed.

FAQ:

When is an Accommodation available on HGV/Booking Suedtirol

An Accommodation is available on Booking Suedtirol when it has a

  • HgvId
  • Property AccoBookingChannel
AccoBookingChannel: [
{
Id: "hgv",
Pos1ID: "2",
BookingId: "12700",
Portalname: "HGV Booking"
}
],
  • IsBookable: true ODH Requests which does this queries at example
    https://tourism.opendatahub.bz.it/v1/Accommodation?rawfilter=isnotnull(HgvId)
    https://tourism.opendatahub.bz.it/v1/Accommodation?rawfilter=in(AccoBookingChannel.[*].Portalname,"HGV Booking")
    https://tourism.opendatahub.bz.it/v1/Accommodation?rawfilter=eq(IsBookable,true)

Does an Accommodation have static prices

The accommodation base information itself has **NO **prices.

The Accommodation has an image on Booking South Tyrol but not on ODH

Syncing issue between ODH and LTS OR
Syncing issue between LTS and HGV

I want a list of Accommodations that are not bookable on HGV

This query should do it:
https://tourism.opendatahub.bz.it/v1/Accommodation?rawfilter=nin(AccoBookingChannel.[*].Portalname,%22HGV%20Booking%22)

Suedtirol.info shows some room pricing information even when no availablity search is done

The static price information of the HGV Room is shown "PriceFrom"

Strategy when to show rooms of which source?

If an accommodation is available on the HGV System we recommend to show the room information from source HGV.

Problems with different sources room information

At example when an accommodation is not available for the requested period on the HGV System but it is available on request by the LTS Availability check, LTS returns all room information from the LTS System

How is a the valid room combination calculated

If more rooms are requested ODH calculates the cheapest room combinations available. If more rooms are requested the HGV and the LTS System returns offers for both rooms shown in the property RoomSeq. It could occur that Room A is offered in offer 1 and offer 2 but is available only 1 time. So Room A can only be used one time in the combination calculation.
ODH represents all valid combinations in the object CheapestOfferDetail

"CheapestRoomCombinationDetail": [
                {
                  "RoomId": "49551",
                  "RoomSeq": 1,
                  "Price": 313,
                  "RoomFree": 1
                },
                {
                  "RoomId": "49552",
                  "RoomSeq": 2,
                  "Price": 313,
                  "RoomFree": 1
                }
              ],
              "Service": "ws",
              "Price": 626
            }