Hotels API

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.

GET/accommodations

Download weekly, then diff lastUpdateDocs

Download the full list about once a week. Fetch a hotel's datasheet again only when its lastUpdate is newer than your last download. Never take prices or availability from the catalogue: those come only from Quote.

Request

Headers

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

Query

firstintegerrequiredSpec
Offset of the first result. Start at 0 and add limit for each page.
limitinteger, max 20000requiredSpec
Page size. Use the maximum, 20000, for a full download.

Response

200 OK

accommodations[]object[]

One entry per hotel.

Child attributes
idstring
Hotel code, used by Quote, datasheets and booking. Formats vary, for example 1000 or MASTER-2267891. Use it as your primary key.
giataIdintegerDocs
GIATA code. Can be null. Use it as a secondary key to match the same hotel across suppliers or your own content.
namestring
Hotel name.
geolocationGeolocationVO
latitude and longitude, as numbers.
countryCodestringDocs
ISO 3166-1 alpha-2, for example ES.
lastUpdatestring
When the hotel's content last changed, for example 2022-10-30 18:36.
paginationPaginationVO

Where this page sits in the full list.

Child attributes
firstResultinteger
Offset of this page.
pageResultsinteger
Number of hotels on this page.
totalResultsinteger
Number of hotels in the whole list.
auditDataAuditResponseVO
Includes traceId (one per token: log it) and authToken (redact it before logging).

Pagination

Request pages until firstResult + pageResults reaches totalResults, or a page comes back empty. The list can be large (the docs sample reported 86,768 hotels), so expect several pages even at the 20,000 maximum. Docs

Which hotels you see

The list contains the hotels of the providers connected to your microsite. Two microsites can see different hotel sets, and a hotel disappears from the list when its provider is disconnected. If a destination returns nothing, check Provider configurations.

The API requires a valid GIATA licence. Talk to your Nava account manager before you launch a catalogue. Docs

Weekly sync

A sync pipeline we recommend. The weekly rhythm and the lastUpdate check come from the docs; the rest is design advice. Unverified

Page through GET /accommodations with limit=20000, off-peak, and upsert id, giataId, name, geolocation, countryCode and lastUpdate.

Mark ids you didn't see this run as inactive, and stop quoting them. Don't hard-delete them: existing bookings may still reference them.

Collect the changed hotels: new ids, plus ids whose lastUpdate is newer than the stored one. Skip the rest. Docs

For each language you serve, fetch datasheets for the changed hotels in batches of 100.

Refresh the facility catalogues and meal plans per language. They are small, so fetch all of them every run.

Decide what to fetch again
// listed: this week's download. stored: Map of id -> your last saved row.
const changed = listed.filter((h) => {
  const known = stored.get(h.id);
  return !known || h.lastUpdate > known.lastUpdate; // new, or content changed
});

const seen = new Set(listed.map((h) => h.id));
const gone = [...stored.keys()].filter((id) => !seen.has(id)); // mark inactive, don't delete

Gotchas

  • No rate limits are documented. Run batches with modest concurrency (2 to 4 parallel requests) and back off on 429 and 5xx. Unverified
  • Give a long-running sync job its own cached token. Refresh it on expiry, or once on a 401 or 403, then fail. That is safe here because static content doesn't need the booking-flow token. Unverified
  • Quoting a hotel id that has left the list returns nothing. Refresh your catalogue at least weekly.
  • Don't cache quote prices in the catalogue. Rates are valid for about an hour, and keys expire after 40 to 60 minutes. Docs

Client requests

Conversations attached to a booking. Ask for an amendment or a cancellation, raise a question or a complaint, reply, and reopen or close the thread. New requests and replies trigger a CLIENT_REQUEST webhook.

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.