The hotel search and hotel details APIs each use a filters > rateTypes field to filter the results based on a specific hotel rate type (e.g., corporate rates).
This guide explains this filter in detail and how to use it in an API call.
The hotel search API lists all available hotel properties based on the search parameters. If you wish to further restrict the hotel results, include a qualified rateTypes filter (e.g., Government rates). See rate type groups to understand the difference between standard rate type and qualified rate type filters.
The hotel details API is used to view the rates and property details (e.g., amenities) for one specific property. This API is called after hotel search to get more details about a specific property selected by the traveler (see hotel booking workflow). In the hotel details API, using the rateTypes filter will list all the matching rates offered by that specific property.
The following are the different values supported in the rateTypes filter:
| Value | Group | Description |
|---|---|---|
PUBLISHED | Standard | The retail rate set by the property for all travelers. |
CORPORATE | Standard | A rate negotiated by your company for its travelers. |
SPOTNANA | Standard | A rate negotiated by Spotnana for its partner organizations. |
TMC | Standard | A rate negotiated by a Travel Management Company (TMC) for its customer organizations. |
BEST_AVAILABLE_RATE | Standard | The lowest publicly available rate during the requested dates. |
REGULAR | Standard | A generic value that includes all the standard group rate types. |
AAA | Qualified | A discounted rate for members of the American Automobile Association (AAA). |
AARP | Qualified | A discounted rate for members of the American Association for Retired Persons (AARP). |
SENIOR_CITIZEN | Qualified | A discounted rate for travelers who meet the property's minimum age requirement for senior rates. |
GOVERNMENT | Qualified | A discounted rate for government employees. |
MILITARY | Qualified | A discounted rate for military personnel. |
MEMBERSHIP | Qualified | A rate available to members of the loyalty program offered by the property. |
The rateTypes values form two groups, standard rate types and qualified rate types. The group determines how a value behaves in filters > rateTypes.
Standard rate types are included in a hotel search result by default. Additionally, if the hotel search API call includes any of the standard rate types (e.g., PUBLISHED), the search result will include all the standard rate types.
The following are the standard rate types in the filters > rateTypes filter:
PUBLISHEDCORPORATESPOTNANATMCBEST_AVAILABLE_RATEREGULAR
Qualified rate types are discounted rates that require traveler eligibility (e.g., AAA member rate). The following are the different qualified rate types:
AAAAARPSENIOR_CITIZENGOVERNMENTMILITARYMEMBERSHIP
Notes:
- If you're selecting a
MEMBERSHIPrate, you'll be required to provide the loyalty membership number during checkout. - For all the other qualified rate types there is no such requirement during checkout. Instead, the property may verify the eligibility at check-in, and if requested, travelers must present proof (e.g., if you booked a AAA rate, you may be asked to present the AAA membership card).
The standard and qualified rate type filters can be combined to provide more granular results. However, the combined use of these filters behaves differently in the hotel search and hotel details APIs. These differences are explained below:
- Qualified rate types can be combined in a hotel search API request. For example, if the
rateTypesis set to["GOVERNMENT", "MILITARY"], then properties offering government rates and properties offering military rates are shown in the search result. - In the hotel search API, qualified rate types take precedence. When the list contains both standard and qualified rate types, the response will return only the qualified rates specified in the filter. Negotiated rates (corporate, TMC, and Spotnana rates) are not retrieved for that search. For example, if
rateTypesis set to["CORPORATE", "AAA"], the results will contain only the properties offeringAAArates. To view a property's standard rates, call the hotel details API. - In the hotel details API, standard and qualified values combine as one list. For example, if
rateTypesis set to["CORPORATE", "AAA", "AARP"], the response will contain the selected property's AAA and AARP rates along with all of its standard rates. In this scenario, the senior citizen, government, and military rates are not returned in the response.
If the optional filters > rateTypes is omitted from the hotel search API then the results will contain published rates and all negotiated rates (corporate, TMC, and Spotnana rates) available to the traveler. Including a single standard rate type, for example ["CORPORATE"], returns the same results as omitting the filters > rateTypes field (i.e., the response contains all standard rates).
However, qualified rate types narrow the search results. The response will contain only properties that have at least one rate matching a qualified rate type in the list. Such a search typically returns fewer properties than an unfiltered search, because qualified rate availability varies by property.
Here's a sample hotel search API request with qualified rate type filters:
{
// ... payload truncated for focus
"filters": {
"rateTypes": ["GOVERNMENT", "MILITARY"]
}
}In the above scenario, a property is returned if it offers a government rate, a military rate, or both. Properties that don't offer a government rate or a military rate are not returned in the search results.
Note: Hotel search returns one price for each property, which is the lowest-priced rate among the rates the search retrieved. This price does not always match the rateTypes filter in the request. For example, when the filter is set to ["AAA"], a property appears in the results only if it offers an AAA rate. However, the displayed price can come from a lower-priced standard rate that was retrieved alongside the AAA rates. Use the hotel details API to view the property's offered rates and their rateType values (all standard rates and the AAA rates) before presenting a specific rate to the traveler.
In the hotel details API, including a standard rate type filter (e.g., CORPORATE) will return all the standard rates for the specific hotel. When you include a qualified rate type filter (e.g., AAA), the response contains only the rates of that type.
The following table explains the rates returned in the response when using a qualified rate type filter:
| Value provided in the list | Rates returned in the response |
|---|---|
AAA or AARP | Both AAA and AARP rates are returned for either of the values. |
SENIOR_CITIZEN | Senior citizen rates. |
GOVERNMENT | Government rates. |
MILITARY | Military rates. |
MEMBERSHIP | Loyalty program member rates. |
Combining a standard and a qualified rate type filter will return all the matching rates for a specific property. For example, ["MEMBERSHIP", "CORPORATE"] returns loyalty program member rates along with all standard rate types.
If you book a loyalty program member rate (i.e., if rateTypes is set to MEMBERSHIP and the corresponding membership rate is booked), you must include the traveler's membership number during checkout. The booking will fail (with an error) when the membership number is absent. See the hotel loyalty programs guide for how to attach loyalty details.