Browse API endpoints

Search hotel stays

Compare full-stay points and cash prices across nearby properties with award availability every night.

POSThttps://apisv2.awardtoolapi.com/api/hotel_search

Example 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.