Search Hotels

Run one live Hotels search and receive ranked hotel listings for a location and stay dates, including hotel id, class rating, guest reviews, and nightly prices. Pass a hotel id to /hotels/info for full details.

Pricing — $ · min $0.01

Minimum 10 credits ($0.01) per call. Records returned above the minimum bill 1 credit ($0.001) each.

Authorization

bearerAuth

AuthorizationBearer <token>

UnifAPI API key. Provider credentials are managed by UnifAPI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

query?string

Optional hotel name or search query. Combine with location to scope the search.

Length1 <= length <= 700

location?|

Search location as a country code/name, DataForSEO location code, full location name, or latitude,longitude,radius coordinate string. Defaults to us.

language?string

Search language as an ISO code or full language name. Defaults to en.

Length2 <= length <= 80

limit?integer

Number of hotels to return. Defaults to 10.

Range1 <= value <= 100

check_in?string

Check-in date. Date in YYYY-MM-DD format.

Match^\d{4}-\d{2}-\d{2}$

check_out?string

Check-out date. Date in YYYY-MM-DD format.

Match^\d{4}-\d{2}-\d{2}$

currency?string

ISO 4217 currency code for prices, such as USD.

Length3 <= length <= 3

adults?integer

Number of adult guests.

Range1 <= value <= 30

children?array<>

Ages of children staying, used to refine availability and pricing.

Itemsitems <= 10

stars?array<>

Filter to hotels with these class ratings, such as [4, 5].

Itemsitems <= 5

min_rating?number

Filter to hotels with at least this guest rating.

Range0 <= value <= 5

sort_by?string

Sort order for results. Defaults to relevance.

Value in"relevance" | "lowest_price" | "highest_rating" | "most_reviewed"

min_price?integer

Minimum price per night.

Range0 <= value

max_price?integer

Maximum price per night.

Range0 <= value

free_cancellation?boolean

When true, only return hotels offering free cancellation.

is_vacation_rentals?boolean

When true, search vacation rentals instead of hotels.

amenities?array<>

Filter to hotels offering these amenities, such as pool or free_wifi.

Itemsitems <= 30

Response Body

`application/json`

curl -X POST "https://example.com/hotels/search" \  -H "Content-Type: application/json" \  -d '{}'

{
  "request_id": "string",
  "data": {
    "query": "string",
    "location": "string",
    "language": "string",
    "observed_at": "string",
    "search_url": "string",
    "result_count": 0,
    "results": [
      {
        "hotel_identifier": "string",
        "title": "string",
        "stars": 0,
        "is_paid": true,
        "location": {
          "latitude": 0,
          "longitude": 0
        },
        "reviews": {
          "rating": 0,
          "votes_count": 0,
          "rating_distribution": {
            "property1": 0,
            "property2": 0
          },
          "extras": {
            "property1": null,
            "property2": null
          }
        },
        "prices": {
          "price": 0,
          "price_without_discount": 0,
          "currency": "string",
          "discount_text": "string",
          "prices_by_dates": [
            {
              "price": 0,
              "currency": "string",
              "check_in_date": "string",
              "check_out_date": "string"
            }
          ],
          "extras": {
            "property1": null,
            "property2": null
          }
        },
        "overview_images": [
          "string"
        ],
        "is_billable": true
      }
    ]
  },
  "billing": {
    "credits_charged": 0,
    "records_charged": 0,
    "balance_remaining": 0,
    "truncated_due_to_balance": true
  }
}

{
  "error": {
    "type": "validation_error",
    "message": "string",
    "request_id": "string",
    "issues": [
      null
    ],
    "billing": {
      "credits_required": 0,
      "credits_charged": 0,
      "records_charged": 0,
      "balance_remaining": 0,
      "truncated_due_to_balance": true
    }
  }
}

{
  "error": {
    "type": "validation_error",
    "message": "string",
    "request_id": "string",
    "issues": [
      null
    ],
    "billing": {
      "credits_required": 0,
      "credits_charged": 0,
      "records_charged": 0,
      "balance_remaining": 0,
      "truncated_due_to_balance": true
    }
  }
}

{
  "error": {
    "type": "validation_error",
    "message": "string",
    "request_id": "string",
    "issues": [
      null
    ],
    "billing": {
      "credits_required": 0,
      "credits_charged": 0,
      "records_charged": 0,
      "balance_remaining": 0,
      "truncated_due_to_balance": true
    }
  }
}

{
  "error": {
    "type": "validation_error",
    "message": "string",
    "request_id": "string",
    "issues": [
      null
    ],
    "billing": {
      "credits_required": 0,
      "credits_charged": 0,
      "records_charged": 0,
      "balance_remaining": 0,
      "truncated_due_to_balance": true
    }
  }
}

{
  "error": {
    "type": "validation_error",
    "message": "string",
    "request_id": "string",
    "issues": [
      null
    ],
    "billing": {
      "credits_required": 0,
      "credits_charged": 0,
      "records_charged": 0,
      "balance_remaining": 0,
      "truncated_due_to_balance": true
    }
  }
}

{
  "error": {
    "type": "validation_error",
    "message": "string",
    "request_id": "string",
    "issues": [
      null
    ],
    "billing": {
      "credits_required": 0,
      "credits_charged": 0,
      "records_charged": 0,
      "balance_remaining": 0,
      "truncated_due_to_balance": true
    }
  }
}

{
  "error": {
    "type": "validation_error",
    "message": "string",
    "request_id": "string",
    "issues": [
      null
    ],
    "billing": {
      "credits_required": 0,
      "credits_charged": 0,
      "records_charged": 0,
      "balance_remaining": 0,
      "truncated_due_to_balance": true
    }
  }
}

{
  "error": {
    "type": "validation_error",
    "message": "string",
    "request_id": "string",
    "issues": [
      null
    ],
    "billing": {
      "credits_required": 0,
      "credits_charged": 0,
      "records_charged": 0,
      "balance_remaining": 0,
      "truncated_due_to_balance": true
    }
  }
}

Search Hotels

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

402application/json

404application/json

429application/json

500application/json

502application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`