Understanding Async Search for Vacation Rentals
The Vacation Rentals API supports two search modes: synchronous and asynchronous. Async mode returns partial results quickly while suppliers continue to respond, giving users a faster initial experience.
Sync vs. Async Mode
| Feature | Sync (isasync: false) | Async (isasync: true) |
|---|---|---|
| Initial response time | Slower (waits for all suppliers) | Faster (returns available results immediately) |
| Response completeness | All results in one response | Partial results, building over time |
| Polling required | No | Yes |
| Status field | "success" | "in_progress" then "success" |
| Best for | Background processing, batch queries | Real-time user-facing search UIs |
How Sync Mode Works
With is_async: false (the default), the API waits for all suppliers to return results before responding.
{
"is_async": false
}Important: When using sync mode, if the response returns status: "in_progress", this means the request timed out before all suppliers finished. In this case, you should re-poll the endpoint with the same x-correlation-id to retrieve the complete results.
Sync Mode Flow
1. POST /hotels/api/v2/properties/vacation-rentals
→ is_async: false
← { status: "success", data: { total: 142, hotels: [...] } }
Done — all results returned.
How Async Mode Works
With is_async: true, the API returns whatever results are available immediately. You poll the same endpoint to get updated results as more suppliers respond.
{
"is_async": true
}Async Mode Flow
1. POST /hotels/api/v2/properties/vacation-rentals
→ isasync: true, x-correlation-id: corrabc123
← { status: "in_progress", data: { total: 45, hotels: [...] } }
Partial results — show these to the user.
- POST /hotels/api/v2/properties/vacation-rentals
→ Same body, same x-correlation-id: corr_abc123
← { status: "in_progress", data: { total: 98, hotels: [...] } }
More results — update the UI.
- POST /hotels/api/v2/properties/vacation-rentals
→ Same body, same x-correlation-id: corr_abc123
← { status: "success", data: { total: 142, hotels: [...] } }
All results returned — stop polling.
Polling Implementation
When using async mode, implement a polling loop that:
- Sends the search request.
- Checks the
statusfield in the response. - If
"in_progress", waits briefly then re-sends the same request with the same correlation ID. - If
"success", stops polling — all results are in.
JavaScript Example
async function searchVacationRentals(correlationId, searchBody) {
const url = 'https://uat.travelapi.ai/hotels/api/v2/properties/vacation-rentals?currency=USD&page=1&limit=50&amenities=true';
let status = 'in_progress';
let results = null;
while (status === 'in_progress') {
const response = await fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-correlation-id': correlationId
},
body: JSON.stringify(searchBody)
});
results = await response.json();
status = results.status;
if (status === 'in_progress') {
// Display partial results to the user
displayResults(results.data.hotels);
// Wait 2-3 seconds before polling again
await new Promise(resolve => setTimeout(resolve, 2500));
}
}
// Final results
displayResults(results.data.hotels);
return results;
}
Python Example
import requests
import time
def searchvacationrentals(correlationid, searchbody):
url = 'https://uat.travelapi.ai/hotels/api/v2/properties/vacation-rentals'
params = {'currency': 'USD', 'page': 1, 'limit': 50, 'amenities': 'true'}
headers = {
'Content-Type': 'application/json',
'x-correlation-id': correlation_id
}
status = 'in_progress'
results = None
while status == 'in_progress':
response = requests.post(url, params=params, headers=headers, json=search_body)
results = response.json()
status = results['status']
if status == 'in_progress':
print(f"Partial results: {results['data']['total']} properties found so far")
time.sleep(2.5)
print(f"Complete: {results['data']['total']} total properties")
return results
Polling Best Practices
| Practice | Recommendation |
|---|---|
| Poll interval | Wait 2-3 seconds between requests |
| Maximum polls | Set a limit (e.g., 10 attempts) to avoid infinite loops |
| Display partial results | Show available results to the user while polling continues |
| Loading indicator | Display a progress indicator while status is "in_progress" |
| Correlation ID | Always reuse the same x-correlation-id from the autocomplete response |
Choosing the Right Mode
| Use Case | Recommended Mode |
|---|---|
| User-facing search page | Async — show results as they arrive |
| API-to-API integration | Sync — simpler implementation, one request |
| Mobile app with loading spinner | Async — faster perceived performance |
| Batch processing or data export | Sync — wait for complete results |
| Price comparison across many destinations | Sync — need full data for comparison |
Handling Edge Cases
No Results Found
If no vacation rentals match the search criteria, the response returns a 404 status code. This can happen in both sync and async modes.
Timeout in Sync Mode
If the sync request times out and returns status: "in_progress", treat it like an async response and poll for the remaining results using the same correlation ID.
Stale Correlation ID
Correlation IDs are linked to a specific autocomplete request. If you need to search a new location, call autocomplete again to get a fresh correlation ID. Do not reuse correlation IDs across different location searches.
Next Steps
Review the full list of supported vacation rental property types and what each type offers.