Skip to main content

Search

Search serves as the initial step in our booking flow, with the objective of verifying availability within the specified date range and for the requested number of guests, either for specific hotels or for hotels in the desired destination. It provides a comprehensive list of available options based on your search criteria. The returned fields include:

  • hotelCode
  • hotelName
  • boardCode
  • paymentType
  • occupancies
  • rooms
  • price
  • rateRule
  • cancelPolicy
  • id

Search Inputs​

When creating your search query, you have three different inputs to fill based on your specific needs:

  1. Criteria
  2. Settings
  3. Filter Search
query {
    hotelX {
    search
      criteria: {}
      settings: {}
	  filterSearch: {}
	}
}
Remember
It's important to note that even if certain fields in the "criteria" or "settings" inputs are labeled as optional, we still need to use some value internally. This value will either come from your query/mutation request or your default settings. You have the ability to manage your default API settings by visiting the API Settings section on our website.

1. Criteria​

The search query offers versatility in search options, with certain fields marked as mandatory (checkIn, checkOut, hotels etc.) and others as optional (language, currency, nationality etc.). This flexibility empowers you to create a personalized Search Query, tailoring the requested fields to your specific needs.

To specify your search criteria you need to use the input HotelCriteriaSearchInput in your query variables:

{
	"criteriaSearch": {
		"checkIn": "2024-10-28",
		"checkOut": "2024-10-29",
		"occupancies": [
			{
				"paxes": [
					{
						"age": 30
					},
					{
						"age": 30
					}
				]
			}
		],
		"hotels": [
			"1",
            "2"
		],
		"currency": "EUR",
		"markets": ["ES"],
		"language": "es",
		"nationality": "ES"
	}
}

Mandatory criteria:

  • checkIn (yyyy-mm-dd)
  • checkOut (yyyy-mm-dd)
  • hotels (We recommend a maximum of 200 hotel codes per request.)
  • destinations (Only if you use the Search by destination plugin and you don't use the hotels field.)
  • occupancies (For multi-room bookings, this array will contain multiple elements, each representing a room, and you'll need to provide occupancy details for each requested room.)

Optional criteria:

  • language
  • currency
  • nationality
  • markets

2. Settings​

Settings are the common configurations used to construct requests to the supplier/s. You need to specify some in your query or mutation, while others are optional. If you skip the optional ones, we'll use default settings to keep your requests consistent and smooth.

To specify your settings you need to use the HotelSettingsInput input in your query variables:

{
    "settings" : {
        "client" : "client_demo",
        "context" : "HOTELTEST",
        "testMode" : true,
        "auditTransactions" : false,
        "timeout" : 5000
    }
}

Mandatory Settings:

  • client
  • context (You have the flexibility to choose between using the supplier's context or your own, depending on which hotel codes you want to use in the query input. If you choose to search for different suppliers using the same query, you must use your own context code and mapping functionality.)
  • timeout (Timeout in milliseconds for all supplier connections. Won't close Buyer connection if exceeded.)

Optional Settings:

  • group
  • auditTransactions
  • suppliers (Each one contains its own code, settings and accesses.)
  • plugins
  • testMode (This flag allows only the accesses checked as test.)
  • businessRules
  • clientTokens (Used to identify the origin of the request, this is only used with some plugins.)
  • operationTimeout (Timeout in milliseconds for Hotel-X connection. Will close Buyer connection if exceeded. Must be higher than timeout.)
Key Recommendations

  • Customize the timeout according to your needs, taking into consideration the maximum value in Search is 25,000ms.

  • Set the auditTransaction to "false" in Search for better performance.

Using your own context and mapping functionality

To request hotel availability using your own hotel codes, utilize the Hotel-X mapping feature. You can achieve this by uploading your mapping files to your FTP account. This approach enables you to make requests with your unique context codes and receive results from all your Sellers with your custom hotel codes.

Filters allow you to precisely tailor the response according to your preferences.

To specify your filters you need to use the input HotelXFilterSearchInput in your query variables. The available filters inside this input are:

  • rateRules: This filter enables you to narrow down the options returned by the suppliers based on the desired rate rules you want to include or exclude.

  • status: Use this filter to determine which status (OK and RQ) will be included or excluded in the response.

  • access: By using the access filter, our system will exclusively include or exclude options from the selected accesses. If you choose not to set any access at all, requests will be made to all available accesses.

All these filters are optional. Example to request only search results from access "2" and options "PACKAGE"

{
    "filterSearch" : {
        "access" : {
            "includes" : [
                "2"
            ]
        },
        "rateRules" : {
            "includes" : [
                "PACKAGE"
            ]
        }
    }
}

You would need to apply the same approach for filtering by specific rate rule (rateRule) and status (status).

Requests Examples​

Search query [1 hotel, 2 rooms: 3 adults 1 child]​

Search query [2 hotels, 1 room: 2 adults]​

As you can see in these responses, you have multiple options with different rates, meal plans, and room types. Additionally, you receive a warning for those options we couldn't return, as the supplier does not provide the commission through the API.

Search Response​

In the response to your search query, you'll receive all the available options that match your criteria. Each option provides various details, such as room type, price, and cancellation policies.

Search output fields

Explore all the search results output fields and their descriptions in our detailed Graphql API Reference section here.

Here are some key points to keep in mind:

Cancel Policies: Refundable Field​

In the room structure response, there is a refundable field. If this field is set to false, it means the room has a 100% cancellation cost, making it non-refundable. If the field returns a null value, it indicates that the Seller doesn't provide this information at this stage and you will obtain this information in the quote step.

Remember

Some Sellers may not include cancellation policies in their availability data. You can learn more about each Seller's specific details in their metadata.

Frequently Asked Questions​

How many hotel codes per request can I request in Search?
We recommend a maximum of 200 hotels: our Hotel-X solution will split them in batches in order to request all of them to each Seller.
Are there any limitations on the number of searches/minute?
Not from Travelgate side, we don't have any limitations on the RPM ("Requests per Minute") in any of our methods. However, some Sellers may have some limitations so we suggest you contact directly with them in order to discuss this information.
Does nationality or market affect the price returned?
Yes, nationality and market might affect the rates received in Search response. This depends on the Seller so if you consider that you should get (or not) different rates depending on the nationality or market, please contact them directly.
How can I search in single or multi mode?

You have the possibility to choose between searching in a single mode vs searching in a multi mode.

Singlemode search

The default mode in Hotel-X allows our Partners to perform one search per Seller connected to their account at a time.

Hotel-X Shopping Flow

When running your Search, you should add the Seller's access code you would like to query.

"filterSearch": {
    "access": {
        "includes": ["2"]
    }
}
Multimode search

The multimode query allows our Partners to search multiple Sellers at the same time in just one request. To search in multimode, start by uploading your hotel mapping files to your FTP. Once the files are processed, you'll have the ability to search multiple Sellers simultaneously by using your own context and hotel codes.

Hotel-X Shopping Flow

1. Specifying the access codes in the filter node in your variables: the query will only be sent to the accesses specified.

"filterSearch": {
    "access": {
        "includes": ["2", "3"]
    }
}

2. Not specifying any accesses: The query will be sent to all the accesses connected to your account (only the ones belonging to the Sellers where the mapping files has been uploaded). This query will also check the value of the "testMode" tag in order to request only the test or production accesses, accordingly.

Why there are so many fields with null value in the Search response?
The number of "null" values returned is determined by the information provided by Sellers. For example, if you include certain fields in your Search Query but the Seller does not have that information available on their side, the value will be returned in our response as "null".
Can I filter the Hotel-X Search results by payment type?
Unfortunately, Hotel-X API does not currently offer the capability to filter search results by payment type.
How can I limit and filter options through optionsQuota and Business Rules?

  • optionsQuota, how to limit the number of options in search response: Thanks to the optionsQuota tag in Hotel-X Pull Buyers API, you are able to control and limit the number of options per board returned in the search response in those cases the Seller allows business rules (you will be able to check this information through our Metadata Query). Note that we have established a system-level limit so that if the OptionsQuota set on your side is higher than the limit established, we will use the one with the lowest value.

    If you don't set any optionsQuota in your search query, we'll use 50 as default value.


  • businessRulesType, how to filter options through Business Rules: These are the 2 types of businessRules that may be applied.

    • CHEAPER_AMOUNT: The cheapest options are returned without exceeding the optionsQuota limit.
    • ROOM_TYPE: It groups the options by room type without exceeding the optionsQuota limit.

    Please note that options are filtered using a limited combination of rooms types. First, we group same room types so you receive options with the same type/classification. For example: Standard-Standard-Standard-Standard, Junior-Junior-Junior-Junior…. Then, we combine the cheapest rooms with the remaining rooms, always checking for duplicates and without execeeding the optionsQuota limit. If a Buyer sets a BusinessRules value, then it will be applied when the number of options returned exceeds the optionsQuota. If the client does not set any BusinessRules values, then the CheaperAmount BusinessRule is applied by default.

What is the lifespan of the Search id?
Search ids do not expire, however, we strongly recommend to transition from Search to Quote as quickly as possible, this will ensure a smoother and more efficient booking process.
What is the occupancyrefID in Search response?
The OccupancyRefID serves as the unique identifier for each room. When you request a single room, the OccupancyRefID will always be "1". However, if you request two rooms, each option will specify the information that belongs to each room (either Room "1" or Room "2").
What does the "units" field indicate in the "rooms" node of the Search response?
The "units" field refers to the number of available rooms of the same type in the hotel. Please note that whether this information is returned or not depends on the Seller.
How can we differentiate a child from an infant? What is the age range of each of them?
The age range for children and infants may vary depending on the Seller's restrictions. To find out the specific age range restrictions for each of your Sellers, you can refer to our Metadata Method or directly contact the Seller.
Can I receive daily prices in Hotel-X Search response?
Yes, you can receive Daily Prices in Search Response (if the Seller returns this information) through the "roomPrice" > "priceBreakdown" fields.
Can I split the rooms returned within an Option and book them separately?
We introduced the option node to ensure that all rooms within a specific option can be booked. If you need to book separate rooms, please send two separate Search requests, one for each room.