Room types

Enable the hierarchy

Add this field to either mapping request shape, or inside each batch record's request:

"include": ["hierarchy"]

The response adds roomHierarchy: the hotel's room types, each holding its rooms. Room IDs, placements, offers and mapping counts are the same with or without it; without the option the field is omitted.

Rooms
└── Bay View Room                     ← room type
    ├── Room, 1 King Bed, Bay View     → supplier offers
    └── Room, 2 Twin Beds, Bay View    → supplier offers
Suites
└── Luxury Suite Sea View
    └── Luxury Suite, 1 King Bed, Sea View → supplier offers

Illustrative hierarchy, not a particular hotel's catalogue or live availability.

What a room type means

With mlr-1 the hierarchy has version: "room-classes-4" and basis: "pair_model". Each room in rooms[] is one bookable room: offers share it only when they state the same tier, class, bed set-up, occupancy, bedrooms, view, features and accessibility. A room type brings together the rooms that differ only in bed set-up or occupancy, such as the King, Twin and Family versions of one room, so you can show a list close to the hotel's own.

Room types sit under their accommodation type (Rooms, Suites, Villas and so on). A room type takes its name from the hotel's own room names when its rooms carry them, without the bed words; otherwise it is named from the supplier offers. Rooms whose type cannot be read stay in unclassifiedRooms[] with a reason.

relationship: "display_group" still holds: rooms in one room type are distinct bookable choices. Book, price and select offers by room and rate IDs, never by class.

On 1,000 blind hotels, mlr-1's room types score B³ F1 91.9 against labels that follow our room definition, at about 29 room types per 100 supplier names where the hotels have 26.

Render the tree

1. Find root nodes in roomHierarchy.classes[] where parentClassId is null: these are accommodation types.
2. Render child classes, the room types, by matching their parentClassId to a type's classId.
3. Resolve every node's direct roomIds against rooms[], then display each room's rates[].
4. Also display unclassifiedRooms[], joined by roomId.

Each room appears exactly once in a node's direct room references or the unclassified list. Parent nodes do not repeat descendants. Keep both visible when expanding a node that has direct rooms and child classes.

classId is a property-scoped browsing reference, stable for the same property, version and room type; price and input-order changes do not change it. Replace a stored hotel's hierarchy as a whole when its version changes.

When the model does not regroup

Strict and consolidated requests, hotels with partner feedback, and any request the pair model cannot answer in time keep the catalogue pipeline's rooms. Their hierarchy is the rule-based proposal: room-classes-2 reads grade terms and supplier shorthand in rooms[].name (Grand Deluxe stays apart from Deluxe; Premier is not Premium; Room or Suite ambiguity stays unclassified), and a completed LLM review returns room-classes-3. Check roomHierarchy.version or basis to tell the two apart.

Cached LLM review

With review enabled, live calls return the rule proposal immediately with roomHierarchy.review.status: "pending". Poll review.statusUrl using the same API key to obtain {"roomHierarchy": ...}. Polling does not rerun mapping or consume mapping quota. Replace only the hierarchy for the inventory that issued that review ID.

reviewed means the LLM response passed the membership and evidence checks. The returned basis becomes llm_reviewed_room_name. Every original room and offer stays intact. An LLM may leave a room unclassified; review does not guarantee correctness or establish room equivalence.

Repeated hotel inventories use the cached review for up to 30 days. Changed room IDs, names, rules or model configuration require a new review; prices and offer order do not. Review results survive service restarts.

The reviewer can recheck a rejected decision once against its original constraints. Only complete, validated decisions become a reviewed result. This can add review time when a correction is needed; synchronous mapping still returns immediately with the rule proposal.

Batch records wait for successful review when enabled; a failed or late review returns a retryable record error. Live calls retain the rule proposal on failure. failed, unavailable and disabled never mean LLM-reviewed. Review is disabled until the deployment has model access configured. No request-body change beyond include: ["hierarchy"] is needed.

Show prices

Send nightlyPrice and currency to sort offers within each room when priced offers share a currency. No class-level minimum price is returned. Dates, occupancy, meals, taxes and cancellation conditions still determine whether prices are comparable.

Refresh prices at shopping time. Prices affect offer ordering, not mapping or class membership. See content and price handling.