Hotel catalogue

The static content endpoints give you the hotels your microsite can sell: names, locations, images, facilities, ratings and destinations. Use them for hotel pages, maps, filters, autocomplete and SEO. Never use them for prices or availability. Those come only from Quote.

Static content calls accept any valid token. They don't need the booking-flow token, so a catalogue job can keep its own. Docs

The endpointsCopy Anchor Link

Limits and parameters come from the spec. Spec Which hotels the list contains depends on the providers connected to your credential's microsite. The documentation's own sample reported 86,768 hotels, so expect several pages. Docs

{
  "auditData": { "authToken": "[REDACTED]", "traceId": "D4AE54C6-…" },
  "accommodations": [
    {
      "id": "1000",
      "giataId": 314272,
      "name": "Hotel Palas Pineda",
      "geolocation": { "latitude": 41.06788, "longitude": 1.17602 },
      "countryCode": "ES",
      "lastUpdate": "2022-10-30 18:36"
    }
  ],
  "pagination": { "firstResult": 0, "pageResults": 1, "totalResults": 86768 }
}

Sync pipelineCopy Anchor Link

Download the list weekly, as the documentation recommends, off-peak, and fetch a datasheet again only when its lastUpdate changed. Docs

weekly, off-peak:
  1. page through GET /accommodations (limit 20000)
     upsert id, giataId, name, geolocation, countryCode, lastUpdate
  2. mark ids not seen in this run as inactive (soft delete: bookings may reference them)
  3. changed = new ids + ids whose lastUpdate is newer than the stored one
  4. for each language you serve:
     GET /accommodations/datasheet for the changed ids, in batches of 100
  5. refresh the facility catalogues and meal plans for each language

daily (optional):
  GET /accommodations/preferred/{micrositeId} for merchandising rails

• No rate limits are documented. We recommend 2 to 4 parallel requests at most, with back-off on 429 and 5xx. Unverified
• Store the raw datasheet JSON next to your normalised columns. Shapes have changed before (see facilities).
• Keep content per language. description and facility translations are language-specific. lang takes the Language enum (EN, ES, AR and others, see Enums).

Code sketchCopy Anchor Link

Pages through /accommodations, then fetches datasheets for the changed ids in batches of 100. catalogue stands for your own storage.

const BASE = process.env.NAVA_BASE_URL!;

type Query = Record<string, string | number | (string | number)[]>;

async function get(token: string, path: string, query: Query) {
  const url = new URL(BASE + path);
  for (const [key, value] of Object.entries(query)) {
    // Arrays become repeated parameters: accommodationId=1000&accommodationId=1003
    for (const item of Array.isArray(value) ? value : [value]) url.searchParams.append(key, String(item));
  }
  const res = await fetch(url, {
    headers: { 'auth-token': token, 'Accept-Encoding': 'gzip' },
    signal: AbortSignal.timeout(180_000),
  });
  const body = await res.json();
  if (body?.auditData?.authToken) body.auditData.authToken = '[REDACTED]';
  if (!res.ok) {
    // Validation errors have no auditData, and static GETs send no Travelc-Trace-Id: log x-request-id too.
    const traceId = body?.auditData?.traceId;
    const requestId = res.headers.get('x-request-id');
    throw new Error(`GET ${path} failed with HTTP ${res.status} (traceId ${traceId}, x-request-id ${requestId})`);
  }
  return body;
}

// 1. The hotel list, up to 20000 per page.
export async function* allAccommodations(token: string, pageSize = 20_000) {
  for (let first = 0; ; first += pageSize) {
    const page = await get(token, '/accommodations', { first, limit: pageSize });
    yield* page.accommodations ?? [];
    const p = page.pagination;
    if (!p || !p.pageResults || first + p.pageResults >= p.totalResults) return;
  }
}

// 2. Datasheets, at most 100 ids per call.
export async function datasheets(token: string, ids: string[], lang = 'EN') {
  const out: any[] = [];
  for (let i = 0; i < ids.length; i += 100) {
    const batch = await get(token, '/accommodations/datasheet', { accommodationId: ids.slice(i, i + 100), lang });
    out.push(...(batch.accommodations ?? []));
  }
  return out;
}

export async function weeklySync(token: string, languages = ['EN', 'AR']) {
  const seen = new Set<string>();
  const changed: string[] = [];
  for await (const hotel of allAccommodations(token)) {
    seen.add(hotel.id);
    const stored = await catalogue.get(hotel.id);
    // lastUpdate looks like "2022-10-30 18:36", so string comparison orders it.
    if (!stored || hotel.lastUpdate > stored.lastUpdate) changed.push(hotel.id);
    await catalogue.upsertSummary(hotel);
  }
  await catalogue.markInactiveExcept(seen); // soft delete, never hard delete
  for (const lang of languages) {
    await catalogue.saveDatasheets(lang, await datasheets(token, changed, lang)); // keep the raw JSON too
  }
}

Data modelCopy Anchor Link

• countryCode in the list is ISO 3166-1 alpha-2. Docs
• The datasheet fields are defined in the spec as IdeaHotelDataVO. Spec

ImagesCopy Anchor Link

• There is no thumbnail. Use images[0], or choose by classification, for example a high-confidence Building or Pool image. Docs
• Images are full-size originals and can be more than 5000 px wide. Serve them through a resizing CDN instead of hot-linking the originals.
• classification.type values differ between the spec and the documentation samples. The spec uses Aerial View and Hallway-Staircase; the samples show AERIAL_VIEW and HALLWAY_OR_STAIRCASE. Spec

Normalise both sides before you compare: upper-case, replace every run of non-alphanumeric characters with _, then drop _OR_. Hallway-Staircase and HALLWAY_OR_STAIRCASE both become HALLWAY_STAIRCASE.

export const normaliseClassification = (type: string) =>
  type.toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/_OR_/g, '_');

normaliseClassification('Hallway-Staircase'); // "HALLWAY_STAIRCASE"
normaliseClassification('HALLWAY_OR_STAIRCASE'); // "HALLWAY_STAIRCASE"
normaliseClassification('Aerial View'); // "AERIAL_VIEW"

FacilitiesCopy Anchor Link

accommodationFacilities[] and roomFacilities[] each hold { id, icon, priority, translations }. Spec

• priority is an integer: higher means more prominent. Sort by it, descending, for a "top amenities" list.
• icon is a CSS class, either Font Awesome (fa-regular fa-grill) or the platform's own (ico-tc-SPA). Map it to your own icon set.
• translations maps a language to the text. Pick the language you render.
• Room facilities add a category: GENERAL, ACTIVITIES, BATHROOM, MEDIA_AND_TECHNOLOGY, FOOD_AND_DRINK, INTERNET, KITCHEN, OUTDOORS, VIEW, LIVING_AREA, BEDROOM or EXCLUSIVE_SERVICES.
• Whether a facility costs extra is not specified. Docs
• The full catalogues come from /facilites/accommodation and /facilites/room (sic), with lang required.

CategoriesCopy Anchor Link

The codes are documented and defined in the spec's HotelCategory enum. Docs

The datasheet gives category as a string ("S4"). The booking flow gives an object, { "code": "S4", "name": "4 STARS" }, with names such as "4 STARS" or "0 KEYS". Normalise both into one type. Spec

type CategoryCode = string; // S1..S6, L1..L5, H1..H5, IN
export const categoryCode = (c: string | { code: string } | undefined): CategoryCode | undefined =>
  typeof c === 'string' ? c : c?.code;

Accommodation types and subtypesCopy Anchor Link

• accommodationType is HOTEL or APARTMENT in the spec. The documentation FAQ writes "Hotel or Apartement", so compare case-insensitively. Spec
• accommodationSubtype has 33 values, for example APARTHOTELS, VILLAS, HOSTEL, RIADS and GUEST_HOUSES. Use it for finer filters. The full list is in Enums. Spec

RatingsCopy Anchor Link

Ratings come from three sources only: Booking.com, Tripadvisor and Expedia. Docs Each entry is { source, numReviews, score }, and score is a string. Spec

Parse score to a number, keep the scale with it, and hide entries with numReviews: 0.

Destinations and search entry pointsCopy Anchor Link

PitfallsCopy Anchor Link

• Hotels disappear. A hotel can drop out of /accommodations when a provider disconnects. Soft-delete it and stop quoting it: quoting an id that vanished from the list returns nothing. Refresh weekly.
• Catalogues are per microsite. Content depends on the microsite and credential, so two microsites can see different hotel sets. If a destination returns nothing, check the supplier connections with GET /providers/configurations/{micrositeId}.
• Don't cache quote prices in the catalogue. Rates are valid for about 1 hour, and combinationKeys expire 40 to 60 minutes after the response that issued them. Docs
• Don't depend on legacy shapes. facilities with includedFacilities[] and includedServices[] still appear in old samples. See facilities.

RelatedCopy Anchor Link

• Accommodations and Datasheets: the list and datasheet references.
• Facilities and Meal plans: the lookup catalogues.
• Destinations: destination codes for Quote.
• The booking flow: where prices actually come from.