Search hotel stays
Compare full-stay points and cash prices across nearby properties with award availability every night.
POST
https://apisv2.awardtoolapi.com/api/hotel_searchExample request
Shell
curl --request POST \
'https://apisv2.awardtoolapi.com/api/hotel_search' \
--header 'Content-Type: application/json' \
--data '{
"api_key": "YOUR_API_KEY",
"location": {
"latitude": 35.6762,
"longitude": 139.6503
},
"radius_miles": 10,
"check_in": "2027-02-15",
"check_out": "2027-02-18",
"max_total_points": 90000,
"room_types": [
"King Room"
]
}'The stay must have a cached award for the same room and rate plan every night. Totals sum the observed nightly rates before any account-specific discounts or free-night benefits.
Request body
api_keystring · Required- An enterprise API key with Hotel access.
locationstring, object or array · Required- A place name, a center with latitude and longitude, or a whole country such as {"country":"JP"}. Supply up to ten locations in an array to search across them. A place name uses its first geocoded match.
check_instring · Required- First award night in YYYY-MM-DD format.
check_outstring · Required- Departure date, excluded from pricing. A stay can cover 1 to 7 consecutive nights.
radius_milesnumber · Optional- Radius around each place or coordinate center, from 0.1 to 100 miles. Defaults to 10. A country selection covers the whole recognized country.
programsstring[] · Optional- Any of hyatt, hilton, marriott, or ihg. Omit or pass an empty list to search all four.
banksstring[] · Optional- Transfer banks for the selected hotel programs. Amex covers Hilton and Marriott, Chase covers Hyatt, IHG and Marriott, and Bilt covers Hyatt and IHG. Capital One and Citi have no partners among the four hotel programs in this inventory. Use amex, bilt, capital one, chase or citi.
hotel_idsstring[] · Optional- Limit results to specific AwardTool property IDs within the location, such as ["hyatt_grandtokyo"].
sub_brandsstring[] · Optional- Match a cached sub-brand by name, such as ["Park Hyatt","Conrad"]. Text matching ignores case.
querystring · Optional- Match part of the property name or formatted address, ignoring case.
min_review_ratingnumber · Optional- Minimum reported Google review rating, from 0 to 5. A property needs a known rating to qualify.
room_typesstring[] · Optional- Match any listed room type by its full cached label, ignoring case.
rate_plansstring[] · Optional- Match any listed award rate plan by its full cached label, ignoring case.
max_total_pointsinteger · Optional- Maximum points for the whole stay in one room and rate plan.
max_total_cash_usdnumber · Optional- Maximum comparable cash price for the entire stay in US dollars. Every night must have a known cash price to apply this filter.
certificatestring · Optional- Filter by AwardTool’s nightly threshold labels. Options are Marriott <= 25k, Marriott <= 35k, Marriott <= 50k, Marriott <= 85k, IHG <= 40k, and Hyatt Category <= 4, 7, or 8 (for example, Hyatt Category <= 4).
certificatesstring[] · Optional- Match any listed certificate using the same labels as certificate. The selected certificate must cover every night. If both fields are supplied, both conditions apply.
max_average_nightly_pointsnumber · Optional- Maximum average points per night, calculated from the full stay before rounding.
max_average_nightly_cash_usdnumber · Optional- Maximum average nightly USD cash comparison. Each night must have a comparable cash price.
max_nightly_pointsinteger · Optional- Require an award rate at or below this point limit on every night in the same room and plan.
max_nightly_cash_usdnumber · Optional- Require a known USD cash comparison at or below this limit on every night.
limitinteger · Optional- Properties per page, from 1 to 200. Defaults to 50.
offsetinteger · Optional- Number of matching properties to skip. Defaults to 0. Use next_offset for the next page.
Example response
JSON · response excerpt
{
"status": 200,
"location": {
"latitude": 35.6762,
"longitude": 139.6503
},
"nights": 3,
"total": 1,
"data": [
{
"id": "hilton_example",
"name": "Example Tokyo Hotel",
"program": "hilton",
"distance_miles": 2.8,
"rooms": [
{
"room_type": "King Room",
"rate_plan": "Standard Room Reward",
"total_points": 90000,
"total_cash_usd": 720,
"cents_per_point": 0.8,
"certificates": []
}
]
}
],
"next_offset": null
}Response fields
location / nights / total- Resolved search location, number of award nights, and total matching properties. An array request returns its resolved locations and counts each property once. An unrecognized single place returns null and zero matches.
data[].id / name / program / distance_miles- AwardTool hotel ID, property name, program, and distance from the nearest matching center. A property matched only by country has a null distance. Use id to retrieve the hotel calendar.
rooms[]- Room types and rate plans available on every requested night, sorted by total points. Properties are ranked by their cheapest matching room.
total_points / total_cash_usd / cents_per_point- Full-stay sum of nightly rates and the resulting redemption value. Cash and value are null when any night lacks a comparable USD rate.
certificates- AwardTool certificate labels whose points or category thresholds are met on every night. The program confirms redemption eligibility.
next_offset- Use this offset with the same filters for the next page of properties. A null value marks the last page.
Errors
400- Check field names, dates, filter values, and pagination parameters.
401 / 403- Supply a valid enterprise API key with access to this product.
405- Send a POST request with a JSON body.
429- The key owner reached a configured quota. Retry after the indicated reset.
503- The cached data service is temporarily unavailable. Retry the same request.