Hotels API

Datasheets

Full hotel content for one hotel or up to 100 at a time, including images, facilities, description, ratings and category. Use it for hotel pages, maps and filters, never for prices.

A datasheet is the full static content of one hotel. Fetch one for a hotel page, or up to 100 per call when you sync your catalogue. Prices and availability never come from here: only Quote returns them.

Up to 100 hotels per call, one parameter per idSpec

Repeat accommodationId once per hotel, for example ?accommodationId=1000&accommodationId=MASTER-1782232&lang=EN. Don't comma-join the ids.

One hotel

GET/accommodations/{accommodationId}/datasheet

Request

Headers

auth-tokenstringrequiredDocs
Any valid token. Static content doesn't need the booking-flow token.
Accept-EncodingstringrequiredDocs
gzip

Path

accommodationIdstringrequired
Hotel code from the accommodation list, for example MASTER-1782232.

Query

langLanguage
Content language, for example EN. description and facility translations depend on it.

Response

One datasheet. Every field is described in Datasheet fields.

200 OK

auditDataAuditResponseVO
Includes traceId (one per token: log it) and authToken (redact it before logging).

Up to 100 hotels

GET/accommodations/datasheet

Request

Headers

auth-tokenstringrequiredDocs
Any valid token.
Accept-EncodingstringrequiredDocs
gzip

Query

accommodationIdstring, repeatable, max 100requiredSpec
One hotel code per parameter. Repeat the parameter for each hotel.
langLanguage
Content language, for example EN.

Response

200 OK

accommodations[]datasheet[]
One datasheet per hotel, with the fields below.
auditDataAuditResponseVO
Log traceId (one per token), redact authToken.

Datasheet fields

Both endpoints return the same datasheet shape. Optional text fields can be empty strings ("").

Datasheet

idstring
Hotel code. Formats vary, for example 1000 or MASTER-2267891.
giataIdintegerDocs
GIATA code. Can be null.
namestring
Hotel name.
categoryHotelCategory (string)Spec
A code such as S4. The booking flow returns an object { code, name } instead, so normalise both.
images[]object[]

Full-size originals, which can be more than 5000 px wide. There is no thumbnail.

Child attributes
urlstring
Image URL. Serve it through a resizing CDN.
width
Width in pixels.
height
Height in pixels.
classificationobject
type (what the image shows, for example Pool) and confidence. Normalise type before you compare it.
accommodationFacilities[]object[]Spec

Hotel facilities.

Child attributes
idinteger
Facility id.
iconstring
A CSS class, for example fa-regular fa-grill or ico-tc-SPA.
priorityinteger
Higher means more prominent.
translationsobject
Map of language to label.
roomFacilities[]object[]Spec
Room facilities, in the same shape as accommodationFacilities[].
destinationIdeaPlaceVO
The hotel's destination: type, code, name and more.
geolocationGeolocationVO
latitude and longitude.
descriptionstring
Plain text with \n line breaks, in the requested language. It often ends in policy lines such as "Pets are not allowed."
ratings[]object[]Docs

Review scores from Booking.com, Tripadvisor and Expedia only.

Child attributes
sourcestring
Booking.com, Tripadvisor or Expedia.
numReviews
Number of reviews. Hide ratings with 0.
scorestring
A string. Scales differ: Booking.com out of 10, Tripadvisor and Expedia out of 5.
phoneNumberstring
Optional.
chainstring
Optional.
addressstring
Optional.
internalRemarkstring
Internal. Never show it to customers.
accommodationTypeAccomodationTypeSpec
HOTEL or APARTMENT. The FAQ writes "Hotel or Apartement", so compare case-insensitively.
accommodationSubtypeAccommodationSubtypeSpec
One of 33 values, for example APARTHOTELS, VILLAS or HOSTEL. Good for finer filters.

Images

  • There is no thumbnail: use images[0]. Docs You can also choose by classification, for example a high-confidence Building or Pool.
  • Images are full-size originals. Proxy them through a resizing CDN rather than sending them to browsers as they are.
  • The spec writes classification types as Aerial View and Hallway-Staircase. Spec The docs samples write AERIAL_VIEW and HALLWAY_OR_STAIRCASE. Docs Normalise both sides before comparing: upper-case, replace every run of non-alphanumerics with _, then drop _OR_. Both examples become HALLWAY_STAIRCASE.
Normalise a classification type
export const normaliseClassification = (s: string) =>
  s.toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/_OR_/g, '_');

normaliseClassification('Hallway-Staircase');    // HALLWAY_STAIRCASE
normaliseClassification('HALLWAY_OR_STAIRCASE'); // HALLWAY_STAIRCASE

The full list is in Enums.

Facilities

Use accommodationFacilities[] and roomFacilities[]. Sort by priority, highest first, for "top amenities", and map icon to your own icon set. Whether a facility costs extra is not specified. Docs

Legacy shapesSpec

The legacy facilities node and /facilities endpoint are deprecated. Use accommodationFacilities[] and roomFacilities[].

Old docs and samples also show facilities { includedFacilities[], nonIncludedFacilities[], otherFacilities[] } and plain-string lists (includedServices[], nonIncludedServices[], otherServices[]). Don't build on them. The full facility catalogues are in Facilities.

Category

The datasheet gives category as a string such as S4. The booking flow gives an object such as { "code": "S4", "name": "4 STARS" }. Normalise both into one type. Spec Codes: S1 to S6 stars, L1 to L5 keys, H1 to H5 suns, IN none. Docs

One category type for both shapes
type Category = { code: string; name?: string };

export const toCategory = (c: string | Category): Category =>
  typeof c === 'string' ? { code: c } : c;

Storing datasheets

  • Keep content per language. description and facility translations change with lang.
  • Store the raw datasheet JSON next to your normalised columns. Shapes have changed before (the facilities deprecation), and the raw copy lets you re-parse without a new download. Unverified
  • Never store or show prices from the catalogue.

Accommodation list

Page through every hotel your microsite can sell, with its code, GIATA id, location and last update time. Download it weekly and use lastUpdate to decide which datasheets to fetch again.

Preferred hotels

The hotels your microsite promotes, returned as full datasheets. Use them for landing pages and recommended rails, then quote them for prices.