Searching for Hotels: Locations, Filters & Pagination
Hotel search is a two-step process. First, resolve a destination name to geographic coordinates using the autocomplete endpoint. Then, use those coordinates to search for available properties. This article covers both steps in full detail, including how to apply filters and paginate through large result sets.
Step 1: Search Locations (Autocomplete)
The autocomplete endpoint resolves a free-text query into structured location results with coordinates. It supports city names, region names, country names, and even specific hotel names.
Endpoint
GET /hotels/api/v2/autocomplete?key={query}
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
key | string | Yes | Search query. Examples: "Miami", "Paris", "Hilton Garden Inn" |
Example Request
GET /hotels/api/v2/autocomplete?key=MiamiAuthorization: {signature}Content-Type: application/json
Example Response
{
"data": [
{
"id": "12345",
"name": "Miami",
"full_name": "Miami, Florida, United States",
"country": "United States",
"state": "Florida",
"location": {
"lat": 25.7617,
"long": -80.1918
}
},
{
"id": "12346",
"name": "Miami Beach",
"full_name": "Miami Beach, Florida, United States",
"country": "United States",
"state": "Florida",
"location": {
"lat": 25.7907,
"long": -80.13
}
}
]
}Response Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique location identifier. |
name | string | Short location name. |
full_name | string | Fully qualified name (city, state, country). |
country | string | Country name. |
state | string | State or province (where applicable). |
location.lat | number | Latitude coordinate. |
location.long | number | Longitude coordinate. |
Important: The response headers will include an x-correlation-id value. You must capture and pass this value in the headers of all subsequent API calls within the same search session. See Session Management & Correlation IDs for details.
*
Step 2: Search Hotels
Once you have coordinates from the autocomplete step, use the hotel search endpoint to find available properties.
Endpoint
POST /hotels/api/v2/properties?page={page}&limit={limit}
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number for pagination. |
limit | integer | 20 | Number of results per page. |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
checkindate | string | Yes | Check-in date in YYYY-MM-DD format. |
checkoutdate | string | Yes | Check-out date in YYYY-MM-DD format. Must be after checkindate. |
occupancy | array | Yes | Array of room occupancy objects (see below). |
lat | number | Yes | Latitude from autocomplete results. |
long | number | Yes | Longitude from autocomplete results. |
countryofresidence | string | Yes | ISO 2-letter country code of the guest (e.g., "US"). |
sort | array | No | Sorting criteria. See Sorting section below. |
filters | object | No | Filter criteria. See Filters section below. |
isasync | boolean | No | Set to false for synchronous results (recommended). |
Occupancy Object
Each element in the occupancy array represents one room:
| Field | Type | Description |
|---|---|---|
adults | integer | Number of adult guests (18+). Minimum: 1. |
childs | integer | Number of children. Set to 0 if none. |
childages | array of integers | Ages of each child. Must have exactly childs elements. Example: [5, 12]. |
Example: Single room, 2 adults
"occupancy": [ { "adults": 2, "childs": 0, "childages": [] }]
Example: Single room, 2 adults + 1 child age 8
"occupancy": [ { "adults": 2, "childs": 1, "childages": [8] }]
Example: Two rooms
"occupancy": [ { "adults": 2, "childs": 0, "childages": [] }, { "adults": 1, "childs": 2, "childages": [5, 10] }]
*
Filters
The filters object lets you narrow search results. All filter fields are optional.
| Field | Type | Description |
|---|---|---|
ratings | array of integers | Star ratings to include. Values: 1 through 5. Example: [4, 5] for 4- and 5-star hotels. |
amenities | array of strings | Filter by amenities. Common values: "Free WiFi", "Pool", "Gym", "Parking", "Restaurant", "Spa", "Pet-friendly", "Airport shuttle". |
minprice | number | Minimum total price (USD). |
maxprice | number | Maximum total price (USD). |
name | string | Filter by hotel name (partial match). Example: "Marriott". |
Example: 4+ star hotels with a pool under $300
"filters": { "ratings": [4, 5], "amenities": ["Pool"], "max_price": 300}
*
Sorting
The sort array controls result ordering. Each element is an object with key and order fields.
| Sort Key | Description |
|---|---|
price | Sort by total rate. |
| Order | Description |
|---|---|
asc | Ascending (lowest first). |
desc | Descending (highest first). |
Example
"sort": [{ "key": "price", "order": "asc" }]
*
Full Search Request Example
POST /hotels/api/v2/properties?page=1&limit=20Authorization: {signature}x-correlation-id: {correlation_id}Content-Type: application/json
{ "checkindate": "2025-06-01", "checkoutdate": "2025-06-05", "occupancy": [ { "adults": 2, "childs": 0, "childages": [] } ], "lat": 25.7617, "long": -80.1918, "countryofresidence": "US", "sort": [{ "key": "price", "order": "asc" }], "filters": { "ratings": [4, 5], "amenities": ["Free WiFi", "Pool"], "maxprice": 400 }, "isasync": false}
Search Response
{
"data": {
"total": 147,
"hotels": [
{
"property_id": "XN00012345",
"name": "Oceanview Resort & Spa",
"ratings": {
"star_rating": 4,
"user_rating": 8.5,
"review_count": 1240
},
"rate": {
"base_rate": 756,
"total_rate": 891.08,
"currency": "USD",
"taxandfees": 135.08,
"recommendedsellingprice": 950,
"saved_price": 58.92
},
"amenities": [
"Free WiFi",
"Pool",
"Spa",
"Restaurant",
"Fitness Center"
],
"image": {
"large": "https://images.xeni.com/hotels/12345/main.jpg"
},
"contact": {
"address": {
"line_1": "123 Ocean Drive",
"city": "Miami Beach",
"state": "FL",
"postal_code": "33139"
}
},
"chain": "Independent",
"distance": 2.4
}
]
}
}Key Response Fields
| Field | Description |
|---|---|
data.total | Total number of matching properties across all pages. |
propertyid | Unique hotel identifier. Use this for detail and availability calls. |
rate.baserate | Room rate before taxes and fees (for the full stay). |
rate.totalrate | Total price including taxes and fees. |
rate.taxandfees | Tax and fee amount. |
rate.recommendedsellingprice | Recommended retail price (for markup calculations). |
rate.savedprice | Savings compared to the recommended selling price. |
distance | Distance from the search center in miles. |
*
Pagination
Results are paginated using the page and limit query parameters.
- The default page size is 20 results.
- The
data.totalfield in the response tells you the total number of matching properties. - Calculate total pages:
Math.ceil(total / limit). - Increment the
pageparameter to fetch the next batch.
Example: Fetching page 2
POST /hotels/api/v2/properties?page=2&limit=20
Use the same request body and headers as the original search. The correlation ID must remain the same throughout the session.
Pagination Tips
- If you receive fewer results than the
limit, you've reached the last page. - Append new results to your existing list rather than replacing them, to build a complete view for the user.
- Avoid requesting very large page sizes. The default of 20 provides a good balance of performance and completeness.