JSON Hotel APIs Guide

This guide provides a general introduction to using the JSON Hotel APIs to search for and book hotels. These terms and concepts are essential to understanding travel development for all the JSON Hotel APIs. It discusses basic travel terms and how those terms are represented in the JSON responses. It also summarizes the general workflow from searching for hotels through booking a room.

In this guide:

• Basic Concepts
• API Versions 11 and 12
• Model Versioning with ODM (Open Data Model)
• Hotel APIs Workflows
• Identifiers in the JSON APIs
• Reference and Full Payload Requests
• Confirmations and Locator Codes
• Pagination (Retrieve Additional Results)
• Passive Segments
• Changes to Sell Requests at Booking
  • Multi-room Sell Requests
  • Price or Guarantee Changes
  • Syncing Reservations after Aggregator Sell Failure

Basic Concepts

The travel industry is based a system that was built decades ago, and thus is deeply standardized but also complex. Because of the critical nature of travel, it's never been possible for travel suppliers or aggregators to fully upgrade to what today's developers and consumers would consider a modern system. Of necessity, many travel terms and booking requirements persist even in modernized interfaces such as the JSON APIs.

The following terms helps you understand how the concepts and processes inherent in the JSON APIs and what they mean for your company's selected travel shopping and booking interface.

PNR, locator code, booking, and reservation

• The term PNR is a travel industry staple. A PNR is a Passenger Name Record. It's the complete booking record containing travel data for all travelers on that reservation. You’ll receive a PNR ID after a successful booking. To prevent confusion, this online help generally uses the term reservationor bookinginstead of PNR to refer to this booking record.

• PNR is often used not only for the booking record, but also for the unique locator code assigned to every booking.

• The locator code is critical - it's a unique string required to retrieve and manage your bookings.

  • Hotel bookings generally return at least three locator codes: a confirmation number from the hotel supplier The hotel that operates the property and makes property and rate details available through a booking platfrom such as Travelport or another aggregator., a locator code from the aggregator A platform that consolidates travel services, schedules, prices, and other details from multiple suppliers into a single interface., such as Travelport or Booking.com (this is often called a PNR locator or just the PNR), and an agency locator specific to your travel agency or company.

  • See Confirmations and Locator Codes for details about how to locate and use these in your applications.

Property, room type, and rate plan

A property is the actual hotel itself. Each hotel room at that property is a room type, such as a deluxe king room, double queen room, and so on. Every room type is available at one or usually multiple rate plans. A rate plan a room type at a property that is available with a package of specific amenities and characteristics, and subject to a set of terms and conditions. Rate plan pricing depends on factors such as on refundability, inclusions such as meals or wifi, and payment terms.

The following are examples of different rate plans for the same room type, and would be available at different prices:

• Non-smoking studio king room with free wifi, parking, and breakfast, no prepayment or deposit required.

• Non-smoking studio king room with free wifi, parking, and breakfast, full prepayment required.

• Pet-friendly double king room with no prepayment or deposit required, no meals or amenities included.

Cancellation policies are usually set by rate plan; for example, free cancellation and 24-hour cancellation might distinguish two otherwise similar rate plans. Cancellation policies can exist at the property level as well.

Brand, chain, aggregator, and GDS

• Hotel brand (brand): A large hospitality company that manages a collection of hotels and resorts, such as Marriott, Accor Hotels, Choice Hotels Corporation, Hilton Hotels Corporation.

• Hotel chain (chain): The unique identity of a hotel or group of hotels (name, standards, etc.) allowing chains to cater to different travelers. Examples include:

  • Marriott: Autograph Collection, Courtyard by Marriott

  • Accor Hotels: Rixos, Sofitel

• Aggregator: An aggregator is a platform that consolidates travel services, schedules, prices, and other details from multiple suppliers into a single interface. Aggregators connect suppliers and travelers. The JSON Hotel APIs gather information about hotels, such as rates, availability, and basic address details from the following two aggregators:

  • the Travelport GDS

  • Booking.com

• GDS: Global Distribution System. A GDS aggregates and distributes air, hotel, and car rental content such as schedules, fares, and upsells. In the JSON APIs, GDS content is distributed from Travelport.

Occupancy

Occupancy is the number of guests (adults and possibly children) per room. A room type generally has a maximum occupancy. Occupancy is required to return accurate pricing and availability, and all JSON Hotel search requests require a guest count.

Booking Workflow

Hotel booking requires a search, either with the JSON Hotel search APIs or another source, an availability check, and booking. Booking requires sending payment, creates the reservation, and returns confirmation numbers and locator codes per above.

See Hotel APIs Workflows below for diagrams and summaries of the required and optional Hotel APIs in the workflow.

Availability and Booking, Overrides and Failures

Hotel inventory can be extremely volatile. To retrieve the most up-to-date inventory and prevent failures at booking, hotel booking requires an availability recheck before booking. The v11 workflow has a separate Availability API request, while v12 SearchComplete returns availability at search in a single request.

Regardless of checking availability, it's always possible that a room or rate is no longer available at booking. If the Hotel APIs find a change to the terms or price between the last availability check and booking, the booking process is paused to allow you to either either proceed with the booking and accept the change/s, or to discard the booking and start a new search.

Other issues may occur at booking; see Changes to Sell Requests at Booking below for details and corrective options.

API-Specific Terms

You'll see the following terms about using the JSON APIs in this online help:

• Full payloadand reference payload requests: Several Hotel API requests carry out the same action but require either all details of the room and rate for which rules or booking is requested (a full payload request), or only an identifier from a previous API response instead of full details (a reference payload request).

• Segments: One hotel room on a booking. For example, if you book 3 rooms, all reservation responses contain 3 segments. Each segment is returned as a separate offer. The Hotel APIs support up to nine rooms on a single booking.

• Offer: Offer is a concept used throughout the ODM Open Data Model. ODM is an open source, object-oriented data model developed by Open Travel, a cross-sector technology alliance for the travel community. The JSON APIs are based on the ODM model using either version 11 or version 12. See the JSON Hotel APIs Guide for details. model of the JSON APIs. For hotel rooms, an offer is similar to a rate plan; for example, hotel searches return hotel rooms available at a specific rate and terms as offers. After booking an offer is used to group each segment, or individual hotel room, on a booking. References to that offer ID link other data, such as comments, to that specific room.

API Versions 11 and 12

The JSON Hotel APIs provide three APIs for searching hotels, which is the first step in any workflow:

• Search by Location: Search for hotels by a geographic location: address, coordinates, or a city or airport code.

• Search by ID: Search for hotels by property ID.

Both of the above APIs are on model version 11 (see the discussion in the following section). You can use either request depending on the search criteria you would like to use. Either request must be followed by an Availability request before you can book a room. Optionally, you can also send a Details request to return additional hotel details such as property images.

• SearchComplete API: Currently in development, SearchComplete combines into a single API the information that in v11 is returned in separate search, details, and availability requests. SearchComplete is based on ODM v12. Functionality on v12 is available only for SearchComplete at this time, so after your SearchComplete request, you can proceed straight to booking with the v11 Create Reservation API. Or, you can request Rules before booking if desired. No additional step is required before booking after a SearchComplete request.

Model Versioning with ODM (Open Data Model)

Open Data Model (ODM) is an open source, object-oriented data model developed by Open Travel, a cross-sector technology alliance for the travel community. All JSON APIs are based on the ODM model using either version 11 or version 12.

• Most Hotel APIs are based on ODM version 11.

• SearchComplete and SearchComplete Pagination are based on ODM v12.

APIs that use model version 11 are referred to in shorthand as v11 APIs. Similarly, SearchComplete is a v12 API.

Hotel APIs Workflows

The following high-level diagrams represents the basic required and optional steps in the hotel booking workflow. Each box in the diagram represents one API call in the workflow.

The following diagram shows the workflow when using v11 APIs for all steps. The minimum required workflow is a hotel search (either by location or property ID), followed by an Availability request, and booking the reservation. Hotel Details and Rules requests are optional.

The next diagram shows the flow when starting with the SearchComplete v12 API. This API combines into a single API the information that in v11 is returned in separate search, details, and availability requests. Model version 12 is available for only search functionality. Use v11 APIs after SearchComplete. You can go straight to booking, or you can request Rules if desired.

The table below summarizes the APIs in the hotel booking workflow and what they do.

Step #	Booking Workflow Step	Description and Notes	API Reference
1	Hotel Search	Search for hotels, either by location or by one or more property IDs. The response returns up to 100 properties. If more are available, you can use pagination to request additional search results.	Search by ID API Reference Search by Location API Reference
2 (optional)	Hotel Details	Request a detailed description and additional images for one specified property.	Hotel Details API Reference
3	Hotel Availability	Availability returns the room types and rates available at one or more specified properties on specified dates. The response returns up to 100 rates. If more are available, you can use pagination to request additional search results.	Hotel Availability API Reference
OR 1, 2, 3	SearchComplete	Currently in development, SearchComplete combines into a single API the information that in v11 is returned in separate search, details, and availability requests. When available, SearchComplete can be used to retrieve in one call the data that in v11 requires three calls. The response returns up to 100 properties. If more are available, you can use pagination to request additional search results.	SearchComplete API Reference
4 (optional)	Hotel Rules	Hotel Rules is an optional request to return the rules, terms and conditions, and hotel policy information for a specific rate. Retrieve these rules by sending an offer ID from an Availability response or a SearchComplete response,	Hotel Rules Reference Payload API Reference Hotel Rules Full Payload API Reference
5	Create Reservation	To complete the booking, send the Create Reservation request, which sends an offer identifier from an Availability response or a SearchComplete response, plus traveler, form of payment (FOP), and payment details.	Create Reservation Reference Payload API Reference Create Passive Reservation Full Payload API Reference

Identifiers in the JSON APIs

The JSON APIs rely on several types of identifiers used for different purposes:

1. Troubleshooting and tracking ids: The JSON Hotel APIs include two objects that can be used to track API calls throughout the workflow:

   • A unique, system-generated transaction ID returned automatically in all API responses. The same value is returned for all API calls that are connected in a workflow, such as if a Create Reservation reference payload request is sent after an Availability request. This transaction ID is returned in two places: the transactionId object and the tvp-trace-id header.

   • Optionally, developers can send their own custom trace ID in the request header to serve as their own tracking number. The v11 APIs send this ID in the traceID header; v12 APIs send this in the TVP-Trace-id header. If a trace ID is sent, all responses in the workflow return that string in the traceId object in the response payload. In the example below, no trace ID was sent in the request header so only transactionId is returned. For details see Transaction and Trace IDs. below

2. Long identifiers: Many objects in the same response return an identifier in Identifier/value. This is always a long system-generated string, for example, 3cecf1be-0b21-4881-8f33-ae11c8d7b708. Such identifier values are unique within the same transaction and across all transactions. These identifiers must frequently be sent in subsequent reference payload requests to refer to an object in a preceding response.

3. Short reference ids: An id is an internal reference number in the id object and is always a short, system-generated string, such as O1 or T1. An id is unique within the response but not across multiple responses.

The following example shows several types of identifiers in an API response.

Reference and Full Payload Requests

Using the identifiers detailed above, many of the JSON APIs allow you to send information either by referring to a previous result. Several APIs also support sending full details instead.

• Reference payload request: Sends reference identifiers from a previous response.
• Full payload request: Sends full details without a reference to any previous response. Can be used to send information returned in a previous JSON API response or from a non-Travelport source.

Confirmations and Locator Codes

Any JSON Hotel reservation response, whether creating a new booking, modifying a booking, or adding a segment to an existing booking, returns the same types of data in the same format. These formats include traveler names in the Traveler object; room, price, and terms and conditions details in the Offer object, and so on. It's important to understand the structure of the Receipt object returned in every reservation response.

At booking, Receipt is where you look to confirm that your booking request succeeded. After booking, Receipt is your reference point for the confirmation numbers and record locators you must send in all subsequent requests to retrieve, modify, or cancel a booking.

Reservation responses return three instances of Receipt. Each is returned with the @type value ReceiptConfirmation. These are for the supplier, the aggregator, and agency. You can identify them as follows:

• Supplier receipt: Confirmation number from the hotel supplier The hotel that operates the property and makes property and rate details available through a booking platfrom such as Travelport or another aggregator.. Required to cancel this booking. Identify this instance with Confirmation/Locator/sourceContext=Supplier
• Aggregator receipt: Locator code from the aggregator A platform that consolidates travel services, schedules, prices, and other details from multiple suppliers into a single interface., such as Travelport or Booking.com. Required to retrieve, modify, or cancel this booking. Identify this instance with Confirmation/Locator/sourceContext=Travelport or another aggregator name if not Travelport.
• Agency receipt: Locator details for your agency PCC provided at provisioning with Travelport.

The code example below shows an excerpt of the entire Receipt object returned at a successful booking. The lines with the supplier confirmation number, the aggregator locator code (in this example, Travelport), and the objects that identify these sources are highlighted in yellow.

Pagination (Retrieve Additional Results)

Availability and search responses in the Hotel APIs use pagination Search setting in offersPerPage that controls the number of offers returned in the initial Search response. When pagination is requested, all offers are cached on the server but only the number in offersPerPage is returned in the initial response. Request additional offers by sending the Pagination request. **Also controls whether search results are cached. Without pagination, results for a journey-based Search request are not cached. If your workflow uses subsequent transactions that reference a Search result, you must request pagination and invoke caching. See the Pagination API Reference. by default. If more than 100 rates or properties are returned in the availability or search response, you can send a follow-on pagination request to retrieve the additional results.

The following APIs support pagination by default:

• Search by Location (v11)

• Search by ID (v11)

• Hotel Availability (v11)

• SearchComplete (v12)

Pagination works similarly across these APIs: The initial response returns up to 100 items. When more than 100 items are returned, send a pagination request to return another page with up to 100 items. The pagination request is a GET request that includes an identifier for the search or availability results and the page number to retrieve.

Search Pagination

For searches, all search responses return up to 100 properties in the initial response, or all available properties if fewer than 100. The search response notes the total number of properties found. The v11 search APIs return an identifier to be used for retrieving additional pages, while v12 SearchComplete returns an identifier only if more than 100 properties are found. You can send the Search Pagination v11 or SearchComplete Pagination v12 request to retrieve each additional page of 100 properties until all available properties have been retrieved.

The v11 search response, for both Search by Location and Search by ID, returns pagination details under the Properties object in the following attributes:

• totalProperties: Total number of properties in the search results across all available pages.

• propertiesPerPage: Number of properties returned in each page of search results. When there are multiple pages, this number is 100; however, the last page of results may return less than 100 properties.

• numberOfPages: The number of pages of search results available. The initial Search response is always page number 1.

In the example excerpt below, 137 properties are available, 100 properties are returned per page, and 2 pages are available. Pagination is available for this response. The second page of results, if retrieved with Search Pagination, would return 37 properties, not 100.

The Search Pagination request must send the value in PropertiesResponse/Properties/Identifier/value in the GET request for each page of results to retrieve. This value is highlighted in the example below.

The SearchComplete response, returns pagination details under the pagination object as follows:

• page: Page number of this response. The initial SearchComplete response is always page number 1.

• pageSize: Number of properties returned in this response.

• totalPages: The number of pages of search results available.

• totalItems: Total number of properties in the search results across all available pages.

• paginationToken: Returned only if pagination is available for this response. This value must be sent in the SearchComplete GET request for each page of results to retrieve.

In the first example excerpt below, this response is page 1 of results, this page returns 2 properties, 1 page of search results are available, and 2 properties are available across all results for this search. Pagination is not available for this response.

Pagination is available for the search results in the second example excerpt below. This response is page 1 of results, this page returns 100 properties, 5 pages of search results are available, and 470 total properties are available across all results for this search. The SearchComplete Pagination request must send the value in pagination/paginationToken in the GET request for each page of results to retrieve. This value is highlighted in the example below.

Availability Pagination

Hotel Availability returns pagination details in CatalogOffering in the following attributes:

• totalCatalogOffering: Total number of rates in the Availability results across all available pages.

• catalogOfferingPerPage: Number of rates returned in each page of Availability results. When there are multiple pages, this number is 100; however, the last page of results may return less than 100 rates.

• numberOfPages: The number of pages of Availability results available. The initial Availability response is always page number 1.

• Identifier/value: Only returned if more than 100 rates are found. Send this value in the subsequent pagination request.

In the example Availability excerpt below, this response returns 61 rates and pagination is not available.

In the next example, two pages of results are available, the response includes an Identifier, and pagination is enabled.

Passive Segments

A passive hotel segment is any segment that was made using anything other than the JSON APIs. Passive segments are informational only. They do not result in a reservation or a change in inventory. Information on a passive segment is not received from or passed to the hotel supplier. Instead, passive segments provide a way to consolidate all booking information, including details from direct hotel bookings or even phone reservations. You can also create a passive segment to act as a placeholder, or as a retention segment to keep the reservation active in the system past the other travel dates on the booking.

The JSON Hotel APIs provide options for creating a new reservation consisting of only a passive segment, adding a passive segment to an existing reservation, or modifying a passive segment.

For details see the Passive Segments Guide.

Changes to Sell Requests at Booking

The following section discusses scenarios that may occur at the time of booking and how to handle them in the JSON APIs.

Multi-room Sell Requests

When making a reservation, Travelport attempts to sell the number of rooms requested, but the supplier may not be able to accommodate the total number of rooms. Each room sold creates a unique hotel segment on the Travelport reservation. A traveler name will be associated with each room with these limitations:

• If the number of rooms requested is equal to the number of traveler names in the request, each room is associated with a unique traveler name.

• If the number of rooms requested is not equal to the number of traveler names in the request, all rooms are associated with the first traveler name.

Price or Guarantee Changes at Booking

All Hotel APIs that either create a new reservation or add a segment to an existing reservation verify the reservation request with the guarantee type and price returned in the Availability response (v11) or SearchComplete response (v12). If there is any difference, the API does not yet create the reservation but instead returns an error notifying you of the change. To accept the change, you send the booking request a second time with the appropriate query parameter/s below. Do not send either of these query parameters in the first reservation request.

• acceptPriceChangeInd: Send this Boolean set to true to proceed with the booking and accept any difference in the current sell price from the total price returned earlier.

• acceptGuaranteeChangeInd: Send with true to proceed with the booking and accept any difference in the guarantee type from the guarantee type returned earlier. Guarantee types checked for differences are guarantee required, deposit required, prepay required.

If you do not want to proceed with the booking because of the changes, send a second request either without these parameters, or send both set to false. Default if not sent is false. Sending a second booking request is not necessary, however, you can simply start a new booking and let these offers expire.

Syncing Reservations after Aggregator Sell Failure

In the event of specific sell failures with Booking.com, you can use the Sync Reservation request to synchronize a Booking.com hotel reservation to a Travelport booking. Sync Reservation allows you to add to your original Create Reservation or Add Reservation request the traveler email address and the Booking.com booking details. The Sync message attempts to add the reservation information into a Travelport reservation as a standard aggregator segment but without re-selling the segment in the aggregator system.

Booking.com requires the traveler’s email address in a hotel sell request. If the sell completes in the Booking.com system, the traveler receives a confirmation email with directions and information needed to synchronize the Travelport booking, provided one of two specific error messages occurred on the original sell attempt.

The following sell failure discussion covers error message explanation and proper sync message handling. For details of the request, see the the Sync Reservation API Reference.