Hotel Search

The hotel search flow begins with location discovery and progresses through hotel content retrieval. This page covers the initial location search capabilities that enable users to find and select destinations for their hotel searches.

Location Auto-Complete

GET /location/search

This endpoint provides autocomplete functionality for geographical locations and specific hotels. It supports searching across cities, airports, regions, and individual hotel properties, returning standardized location objects that can be used in subsequent hotel searches.

Request

The endpoint accepts query parameters to filter and search for locations:

query: (string) The search query string for location auto-complete
types: (string?) A comma-separated list of location types to filter by. Valid values are CITY, AIRPORT, REGION, and HOTEL.
limit: (number?) Maximum number of results to return

Response

Returns an array of Location Search Result objects matching the search query.

GET /location/search?query=toronto&limit=2

[
    {
        "type": "CITY",
        "name": "Toronto",
        "country": "United States",
        "region": "Illinois",
        "public": "58524b9e-313c-4e69-a92e-ffca5c0f2b7f",
        "score": 11
    },
    {
        "type": "AIRPORT",
        "name": "Lester B. Pearson International Airport",
        "country": "Canada",
        "region": "Ontario",
        "iata": "YYZ",
        "public": "292104e4-5efe-44a5-9ac3-138faf2c52ef",
        "score": 8.8
    }
]

🛎 The public ID from any location result can be used directly in hotel search requests.

Location Types

The API returns four types of location results:

CITY: Municipal areas and urban centers
AIRPORT: Airport locations that can serve as search centers
REGION: Broader geographical regions like provinces or tourist areas
HOTEL: Specific hotel properties for direct booking

⛳ Airport locations include both the airport itself and the surrounding area for hotel searches.

Possible Errors

Status Code	Error	Reason
400	[Validation Error]	Invalid query parameters or search string
429	[Rate Limit Exceeded]	Too many requests in short time period
401	Unauthorized	Invalid or missing API key
404	Invalid Key Exception	API key is invalid or inactive

Hotel Session Initiation

POST /hotel/initiate

This endpoint creates a session context for hotel searches without immediately triggering the search process. This design accommodates both location-based searches and direct hotel searches, where the latter may not require the asynchronous search flow.

🛎 Unlike flight searches, hotel session creation and search execution are separate operations, allowing for more flexible search patterns.

Request

POST /hotel/initiate

{
  "query": {
    "location": "292104e4-5efe-44a5-9ac3-138faf2c52ef",
    "check_in_date": "2025-10-08",
    "check_out_date": "2025-10-12",
    "channel": "MEMBER",
    "device": "MOBILE"
  },
  "passengers": [
    {
      "code": "ADT"
    },
    {
      "code": "CHD"
    }
  ],
  "preferences": {
    "account_id": "e3b34b0e-e812-41fc-a247-35ba3106af2d"
  }
}

Request Parameters

query: (Hotel Session Query) The search parameters for the hotel session
passengers: (Array<Record>) List of passengers for the hotel booking
- code: (Passenger Code) Currently only ADT (adult) is supported, CHD (child) support coming soon
preferences: (Hotel Preferences?) Search preferences

Required Headers

x-forwarded-for: User's IP address must be provided
user-agent: (optional) Will be used to infer device type in future versions

Response

Returns a Session object with flow set to HOTEL.

POST /hotel/initiate

{
  "flow": "HOTEL",
  "expireAt": "2025-01-24T23:55:00",
  "createdAt": "2025-01-24T21:55:00",
  "public": "77553c48-6ecf-41ba-a4fa-ba48418aebf2"
}

⛳ Hotel sessions have a default 2-hour expiration time and use the HOTEL flow type to distinguish them from flight search sessions.

Possible Errors

Status Code	Error	Reason	Reason Code
401	Unauthorized	Invalid or missing API key
404	Invalid Key Exception	API key is invalid or inactive	ORX_INVALID_API_KEY
400	[VALIDATION ERROR]	Failed Validation
404	Location Not Found	Location with provided public ID not found	ORX_LOCATION_NOT_FOUND

Hotel Search Initiation

POST /hotel/[sessionId]/search

This endpoint initiates the asynchronous process of retrieving hotel availability and rates from multiple providers. The search operates on streams, where each stream represents a connection to a specific hotel content provider.

🛎 Hotel searches are asynchronous and use streaming providers. Use the search status endpoint to monitor progress and the availability endpoint to retrieve results.

Request

This endpoint does not require a request body - the search parameters are defined during session creation.

POST /hotel/[sessionId]/search

Response

Returns a Hotel Search Response with the current search status and stream information.

POST /hotel/[sessionId]/search

{
    "status": "IN_PROGRESS",
    "streams": [
        {
            "id": "b4ee9428-63a5-4c1f-b78f-c41f28849edf",
            "credential_id": "b4ee9428-63a5-4c1f-b78f-c41f28849edf",
            "status": "IN_PROGRESS"
        },
        {
            "id": "a0fc581f-5000-4660-a16a-f824792122d0",
            "credential_id": "a0fc581f-5000-4660-a16a-f824792122d0",
            "status": "IN_PROGRESS"
        }
    ]
}

Possible Errors

Status Code	Error	Reason
401	Unauthorized	Invalid or missing API key
404	Invalid Key Exception	API key is invalid or inactive
404	[Session Not Found]	The specified session ID does not exist or has expired
400	Search Already Initiated	A search has already been started for this session
400	Invalid Session Type	The session ID does not correspond to a hotel search session
500	NDCx Internal Error	Unknown

Hotel Search Status

GET /hotel/[sessionId]/search

This endpoint returns the current status of the hotel search streams, allowing clients to poll for updates as hotel data becomes available from different providers.

Request

GET /hotel/[sessionId]/search

Response

Returns a Hotel Search Response with updated status information for all search streams.

GET /hotel/[sessionId]/search

{
    "status": "COMPLETED",
    "streams": [
        {
            "id": "b4ee9428-63a5-4c1f-b78f-c41f28849edf",
            "credential_id": "b4ee9428-63a5-4c1f-b78f-c41f28849edf",
            "status": "COMPLETED"
        },
        {
            "id": "a0fc581f-5000-4660-a16a-f824792122d0",
            "credential_id": "a0fc581f-5000-4660-a16a-f824792122d0",
            "status": "COMPLETED"
        }
    ]
}

🛎 Poll this endpoint regularly to track search progress. The overall status becomes COMPLETED, ERRORED or TIMED_OUT when all streams finish processing.

Possible Errors

Status Code	Error	Reason
401	Unauthorized	Invalid or missing API key
404	Invalid Key Exception	API key is invalid or inactive
404	[Session Not Found]	The specified session ID does not exist or has expired
400	[Search Not Initiated]	No search has been started for this session

Hotel Availability Results

GET /hotel/[sessionId]/availability

This endpoint provides live hotel data from the search process. It supports incremental updates through timestamp-based polling, returning newly added properties in the new array and updated properties in the updated array when a timestamp is provided.

Request

Query parameters for incremental updates:

timestamp: (string?) Timestamp from previous response for incremental updates

GET /hotel/[sessionId]/availability?timestamp=2025-01-24T21:55:00Z

Response

Returns a Hotel Availability Response with hotel data and search status.

GET /hotel/[sessionId]/availability

{
  "new": [
    {
      "hotel_information": {
        "hotel_name": "Fairmont Royal York Gold Experience",
        "rating": "5",
        "distance": {
          "distance": "20.34",
          "UOM": "KM"
        },
        "images": [
          {
            "src": "https://i.travelapi.com/lodging/38000000/37230000/37220300/37220227/9efb2546_z.jpg",
            "alt": "Primary image"
          },
          {
            "src": "https://i.travelapi.com/lodging/38000000/37230000/37220300/37220227/758bf1a7_z.jpg",
            "alt": "Room"
          },
          {
            "src": "https://i.travelapi.com/lodging/38000000/37230000/37220300/37220227/54c852f4_z.jpg",
            "alt": "Room"
          },
          {
            "src": "https://i.travelapi.com/lodging/38000000/37230000/37220300/37220227/ce4ee48b_z.jpg",
            "alt": "Room"
          }
        ],
        "chain_code": "-1",
        "hotel_code": "37220227",
        "master_chain_name": "Accor Hotel Brands",
        "master_chain_code": "RT",
        "address": {
          "city_name": "Toronto",
          "country_code": "CA",
          "address": "100 Front St West-Building A",
          "city_code": null,
          "postal_code": "M5J1E3",
          "phone": ["1-416-3682511"],
          "fax": [],
          "location": {
            "latitude": "43.64599",
            "longitude": "-79.38141",
          }
        }
      },
      "credential_id": "b4ee9428-63a5-4c1f-b78f-c41f28849edf",
      "rates_info": [
        {
          "rate_description": {
            "start_date": "2025-10-08",
            "end_date": "2025-10-12",
            "tax_inclusive": false,
            "number_of_nights": 4,
            "refundable": true,
            "commissionable": true,
            "discount_codes": [],
            "pay_at_hotel": false
          },
          "rate_price": {
            "fees": {
              "total": "0.00",
              "description": null
            },
            "taxes": {
              "total": "1104.52",
              "description": null
            },
            "commission": {
              "type": "FIXED",
              "amount": "452.00"
            },
            "average_nightly_rate": "1497.63",
            "average_nightly_rate_before_tax": "1221.50",
            "amount_after_tax": "5990.52",
            "amount_before_tax": "4886.00",
            "currency": "CAD"
          },
          "local_rate_price": null,
          "expireAt": "2025-09-24T01:08:57.332Z",
          "createdAt": "2025-09-23T23:09:05.577Z",
          "public": "51c3fb0a-6414-495f-84ee-dd26bee0cf97"
        }
      ],
      "expireAt": "2025-09-24T01:08:57.332Z",
      "public": "24caae5e-52a0-4bdd-a84d-f08b4057bb81",
      "createdAt": "2025-09-23T23:09:06.206Z",
      "updatedAt": "2025-09-23T23:09:06.206Z"
    }
  ],
  "updated": [
    {
      "hotel_information": {
        "hotel_name": "Hampton Inn by Hilton Brampton Toronto",
        "rating": "3",
        "distance": {
          "distance": "10.08",
          "UOM": "KM"
        },
        "images": [
          {
            "src": "https://i.travelapi.com/lodging/6000000/5410000/5406600/5406597/91c982f3_z.jpg",
            "alt": "Primary image"
          },
          {
            "src": "https://i.travelapi.com/lodging/6000000/5410000/5406600/5406597/44e4961a_z.jpg",
            "alt": "Lobby"
          },
          {
            "src": "https://i.travelapi.com/lodging/6000000/5410000/5406600/5406597/930ab092_z.jpg",
            "alt": "Lobby"
          }
        ],
        "chain_code": "-5",
        "hotel_code": "5406597",
        "master_chain_name": null,
        "master_chain_code": null,
        "address": {
          "city_name": "Brampton",
          "country_code": "CA",
          "address": "8710 The Gore Road",
          "city_code": null,
          "postal_code": "L6P0B1",
          "phone": ["1-905-488-4888"],
          "fax": ["1-905-488-4889"],
          "location": {
            "latitude": "43.76562",
            "longitude": "-79.65842",
            "_id": "68d3289105bcd16cf744db8a"
          }
        }
      },
      "credential_id": "b4ee9428-63a5-4c1f-b78f-c41f28849edf",
      "rates_info": [
        {
          "rate_description": {
            "start_date": "2025-10-08",
            "end_date": "2025-10-12",
            "tax_inclusive": false,
            "number_of_nights": 4,
            "refundable": false,
            "commissionable": true,
            "discount_codes": [],
            "pay_at_hotel": true
          },
          "rate_price": {
            "fees": {
              "total": "0.00",
              "description": null
            },
            "taxes": {
              "total": "138.59",
              "description": null
            },
            "commission": {
              "type": "FIXED",
              "amount": "26.81"
            },
            "average_nightly_rate": "190.62",
            "average_nightly_rate_before_tax": "155.97",
            "amount_after_tax": "762.47",
            "amount_before_tax": "623.88",
            "currency": "CAD"
          },
          "local_rate_price": null,
          "expireAt": "2025-09-24T01:08:57.332Z",
          "createdAt": "2025-09-23T23:09:05.691Z",
          "public": "aa1a6114-c9ad-4299-abba-ee9325efeb74"
        }
      ],
      "expireAt": "2025-09-24T01:08:57.332Z",
      "public": "23a45288-ee5e-40a8-926f-33204eadecca",
      "createdAt": "2025-09-23T23:09:06.291Z",
      "updatedAt": "2025-09-23T23:09:06.291Z"
    }
  ],
  "timestamp": "1758668948729",
  "status": "IN_PROGRESS"
}

⛳ When no timestamp is provided, all available results are returned in the new array. Use the returned timestamp for subsequent incremental requests.

Possible Errors

Status Code	Error	Reason
404	[Session Not Found]	The specified session ID does not exist or has expired
400	Search Not Initiated	No search has been started for this session
400	[Validation Error]	Invalid query parameters or search string

Retrieve Order Property & Rate Details