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

Header Parameters

Unifapi-Version?string

Pin the API version an integration was built against (date-based, e.g. 2026-07-01). Omit to use the current version. Public URL paths stay stable and unversioned; breaking changes ship under a new dated version and are announced with Deprecation and Sunset response headers. The served version is echoed in every response's Unifapi-Version header. Policy: https://unifapi.com/versioning.md

Idempotency-Key?string

Client-supplied unique key that makes a write request safe to retry. If a request with the same key was already processed, the original response is replayed (with Idempotency-Replayed: true) instead of executing — and billing — again. Send a fresh UUID per logical operation. Best-effort with a 24h window.

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.

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.

limit?integer

Number of hotels to return. Defaults to 10.

check_in?string

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

check_out?string

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

currency?string

ISO 4217 currency code for prices, such as USD.

adults?integer

Number of adult guests.

children?array<>

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

stars?array<>

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

min_rating?number

Filter to hotels with at least this guest rating.

sort_by?string

Sort order for results. Defaults to relevance.

min_price?integer

Minimum price per night.

max_price?integer

Maximum price per night.

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.

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

Header Parameters

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`