Vacation Rentals Frequently Asked Questions

This article answers common questions about the Xeni Vacation Rentals API.

General

How is the Vacation Rentals API different from the Hotels API?

The Vacation Rentals API searches for alternative accommodation types such as condos, apartments, cottages, houseboats, mobile homes, aparthotels, and condominium resorts. It uses a different search endpoint path (/hotels/api/v2/properties/vacation-rentals) but shares the same autocomplete endpoint as the Hotels API. The request and response structures are similar, with the addition of the vacation_rentals property type filter.

Is vacation rentals a separate API or part of the Hotels API?

It is part of the same API infrastructure. The autocomplete endpoint is shared, and the search endpoint follows the same patterns. The key difference is the URL path (/vacation-rentals appended to the properties endpoint) and the vacation_rentals filter parameter in the request body.

Do I need separate credentials for vacation rentals?

No. The same API credentials and authentication used for the Hotels or Resorts API work for Vacation Rentals.

Property Types

Can I filter by property type?

Yes. Use the vacation_rentals array in the search request body to filter results by one or more property types:

{
  "vacation_rentals": [
    "Cottage",
    "Apartment"
  ]
}

Supported values: "Condo", "Apartment", "Cottage", "Houseboat", "Mobile Home", "Aparthotel", "Condominium Resort".

What happens if I do not specify a property type?

If you omit the vacation_rentals parameter or pass an empty array, the search returns all available vacation rental property types for the given location and dates.

Are the property type values case-sensitive?

Yes. Use the exact values as documented (e.g., "Cottage" not "cottage", "Mobile Home" not "mobile home").

Search and Correlation ID

What is the correlation ID?

The correlation ID is a unique value returned in the x-correlation-id response header from the autocomplete endpoint. It links your autocomplete lookup to subsequent search requests. The search endpoint requires this header to function.

Can I search without calling autocomplete first?

No. The autocomplete endpoint provides the correlation ID, place ID, and coordinates needed for the search request. You must call autocomplete first.

Can I reuse a correlation ID for multiple searches?

A correlation ID is tied to a specific autocomplete request. For the same destination, you can use it for multiple search requests (e.g., different dates or occupancy). However, if you search a new destination, you should call autocomplete again to get a fresh correlation ID.

What happens if I omit the correlation ID?

The search returns a 400 error indicating that the correlation ID is missing.

Pricing

How does pricing work for vacation rentals?

Each property in the search results includes a rates object with the following fields:

Can I change the currency?

Yes. Pass the desired currency as a query parameter: currency=EUR, currency=GBP, etc. All prices in the response will be in the specified currency. If an unsupported currency is provided, the API returns a 400 error.

Are prices per night or per stay?

The retailprice and baserate fields are per night. The totalrate and taxand_fees fields are for the full stay duration.

Filtering and Sorting

What filters are available?

The following filters can be passed in the filters object:

How do I sort results?

Use the sort array in the request body:

{
  "sort": [
    {
      "key": "price",
      "order": "asc"
    }
  ]
}

How does pagination work?

Use the page and limit query parameters. Pages start at 1, and the maximum limit per page is 50. Check data.total in the response to determine how many pages of results exist.

Async Mode

When should I use async mode?

Use async mode (is_async: true) when building user-facing search experiences where you want to display results as quickly as possible. The API returns partial results immediately, and you poll for more results until all suppliers have responded.

How do I know when all results are in?

Check the status field in the response. When it equals "success", all results have been returned. While it equals "in_progress", continue polling with the same correlation ID.

What if sync mode returns "in_progress"?

If a sync request times out before all suppliers respond, the response may have status: "in_progress". Treat this like an async response and poll again with the same correlation ID.

Multi-Language Support

Can I get results in other languages?

The autocomplete endpoint supports the Accept-Language header. Pass a language code (e.g., "ar" for Arabic, "es" for Spanish, "fr" for French) to receive localized location names.

GET /hotels/api/v2/autocomplete?key=paris
Accept-Language: es

Are property names and descriptions translated?

Property names and descriptions are provided as registered by the property and may not be available in all languages. The Accept-Language header primarily affects autocomplete location results.

Errors

What are the common error codes?

Support

For additional help with the Vacation Rentals API, contact Xeni support at customersupport@xeni.com.