GET

Agoda Hotel Search API

Find hotels and matching prices for a city, stay, and guest group.

Endpoint

GET https://api.stayapi.com/v1/agoda/search

Authenticate with X-API-Key. Supply exactly one of city_id or a compatible url, plus the stay dates.

Parameters

Parameter	Type	Required	Rules
city_id	integer	One of city_id / url	1–2147483647. Phuket is 16056.
url	string	One of city_id / url	Compatible Agoda search URL; see rules below.
check_in	date	Yes, directly or in URL	YYYY-MM-DD; today through 365 days ahead.
check_out	date	Yes, directly or in URL	After check-in; maximum 90 nights.
adults	integer	No	Default 2; 1–60; must be at least rooms.
rooms	integer	No	Default 1; 1–9.
children	integer	No	Default 0; 0–9. Without explicit ages, each child uses age 8.
children_ages	string	No	Up to nine comma-separated integer ages 0–17. Nonblank ages override children; omitted or blank uses children with age 8.
currency	string	No	Default USD; normalized three-letter currency code.
page	integer	No	Default 1; 1–1000.

Search URL compatibility

The REST endpoint accepts HTTPS URLs at agoda.com/search or www.agoda.com/search. Supported URL fields are city, checkIn, checkOut, adults, rooms, children, childAges, currency, and los (length of stay). The optional cid tracking parameter is accepted without changing the search. URLs must not contain credentials, ports, fragments, or duplicate query keys. Conflicting explicit values or unsupported filters return 400. Hotel URLs and other hosts or paths are not search inputs.

Example: https://www.agoda.com/search?city=16056&checkIn=2027-05-15&checkOut=2027-05-17. URL-encode the entire value when passing it as url. The playground and MCP tool use city_id directly.

Response and pricing

The response includes success, city_id, nullable city_name, effective search occupancy and dates, currency, hotels, pagination, and a UTC ISO retrieved_at timestamp. Each card has a numeric hotel_id, name, boolean available, and nullable url, star_rating, latitude, and longitude.

price_per_room_per_night and stay_price each contain exclusive, taxes_and_fees, and total. They reflect the cheapest matching-currency whole-booking offer. stay_price covers the requested rooms and entire stay. Source rounding means multiplying nightly values may not exactly reproduce whole-booking values. Unavailable cards have null prices.

Illustrative response:

{
  "success": true,
  "city_id": 16056,
  "city_name": "Phuket",
  "search": {
    "check_in": "2027-05-15",
    "check_out": "2027-05-17",
    "adults": 2,
    "rooms": 1,
    "children": 0,
    "children_ages": []
  },
  "currency": "USD",
  "hotels": [
    {
      "hotel_id": 10884,
      "name": "Banyan Tree Phuket",
      "url": null,
      "star_rating": 5.0,
      "latitude": null,
      "longitude": null,
      "available": true,
      "price_per_room_per_night": {
        "exclusive": 150.0,
        "taxes_and_fees": 30.0,
        "total": 180.0
      },
      "stay_price": {
        "exclusive": 300.0,
        "taxes_and_fees": 60.0,
        "total": 360.0
      }
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 10,
    "returned_count": 1,
    "total_filtered_hotels": 1
  },
  "retrieved_at": "2026-10-14T12:00:00Z"
}

Pagination and limitations

Request the next page to continue in the provider's default ranking. page_size is fixed at 10, but the actual card count can differ, including 11 cards when an unavailable card is present. returned_count is the actual array length; total_filtered_hotels is the provider-reported total. There is no has_more, configurable page size, sorting, or filtering parameter. Hotel ordering and totals can change between calls.

A valid empty search returns hotels: [] with returned_count: 0. For a specific hotel name, use hotel name lookup. Use a selected hotel_id with hotel prices for room-level offers or hotel reviews.

Errors

Failures return RFC 7807 Problem Details: 400 for invalid or conflicting parameters, 502 for an upstream failure, and 503 when temporarily unavailable. Missing or incorrectly typed required parameters return 422. Authentication and account limits can return 401, 402, or 429 and apply. Failed searches never return a successful empty list.

{"success": true, "city_id": 16056, "city_name": "Phuket", "search": {"check_in": "2027-05-15", "check_out": "2027-05-17", "adults": 2, "rooms": 1, "children": 0, "children_ages": []}, "currency": "USD", "hotels": [{"hotel_id": 10884, "name": "Banyan Tree Phuket", "url": null, "star_rating": 5.0, "latitude": null, "longitude": null, "available": true, "price_per_room_per_night": {"exclusive": 150.0, "taxes_and_fees": 30.0, "total": 180.0}, "stay_price": {"exclusive": 300.0, "taxes_and_fees": 60.0, "total": 360.0}}], "pagination": {"page": 1, "page_size": 10, "returned_count": 1, "total_filtered_hotels": 1}, "retrieved_at": "2026-10-14T12:00:00Z"}