Holidu Rental Search API Documentation Search Holidu vacation rentals by destination or map area, with dates, guests, price band, property type, bedrooms, rating and amenity filters. Each offer has price (total, per night, discount, currency), details, bed types, location, provider, rating, photos in four sizes, amenities, cancellation policy and booking flags.
Pages: 30 offers per page, page 1 to 101. A page above 101 is rejected. Every page of one query comes from one result set. Holidu changes its offer set after about 12 minutes, so a deep walk should run fast.
Price: the price band needs check_in and check_out and applies to the total of the stay. Without dates, prices are per night. Totals marked is_exact false are estimates, so an estimate can sit slightly outside the band.
Sort: sort and order only reorder the returned page. They never change which offers a page holds.
Filters: a card that contradicts the type, bedroom or exact price filter fails the request. Unrated offers are removed when a rating filter is set; removed_unrated shows how many.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
This endpoint has no required query parameters.
19 optional filters available.
string
Optional
Destination text, e.g. Paris. Send query or a map area, not both.
coffee shops
number
Optional
Map area, north-east corner latitude. Send all four map values together.
10
number
Optional
Map area, north-east corner longitude.
10
number
Optional
Map area, south-west corner latitude.
10
number
Optional
Map area, south-west corner longitude.
10
string
Optional
Check-in date, YYYY-MM-DD, today or later. Send with check_out.
example
string
Optional
Check-out date, after check-in, at most 30 nights.
example
integer
Optional
Number of adults, 1 to 30. Defaults to 2.
10
string
Optional
Comma-separated ages of the children, each 0 to 17, up to 6. Example: 5,7.
example
string
Optional
Comma-separated: VACATION_APARTMENT, VACATION_HOME, VILLA, HOTEL.
example
integer
Optional
Minimum number of bedrooms. A studio counts as one.
10
integer
Optional
Minimum guest rating bucket: 90, 80, 70, 60, or 0 for properties without rating.
10
string
Optional
Comma-separated amenity codes from the filters endpoint, e.g. POOL,KITCHEN. All must apply.
example
integer
Optional
Minimum total of the stay in the market currency. Needs check_in and check_out.
10
integer
Optional
Maximum total of the stay in the market currency. Needs check_in and check_out.
10
integer
Optional
Page number, 1 to 101. Defaults to 1.
1
string
Optional
Reorders the returned page: price, total_price, rating, distance.
relevance
string
Optional
asc or desc. Defaults to the natural order of the sort.
example
string
Optional
Country site: com (USD), de (EUR), uk (GBP) or fr (EUR). Defaults to com. An unknown value is rejected.
US
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
data
meta
success
{
"data": {
"page": 1,
"sort": "rating",
"query": "Paris",
"total": 10,
"market": "com",
"offers": [
{
"id": "57639048",
"url": "https://www.holidu.com/d/57639048",
"tags": [],
"usps": [
{
"id": "USP_PEOPLE",
"unit": null,
"group": "PEOPLE",
"value": 4,
"format": "NUMBER"
},
{
"id": "USP_BED_ROOM",
"unit": null,
"group": "LAYOUT",
"value": 2,
"format": "NUMBER"
}
],
"dates": {
"to": "2027-03-18",
"from": "2027-03-14"
},
"likes": null,
"price": {
"ccy": "USD",
"daily": 327,
"total": 1310,
"nights": 4,
"currency": "USD",
"is_exact": false,
"discount_type": null,
"discount_amount": null,
"discount_percentage": null,
"discount_description": null,
"strike_through_daily": null,
"strike_through_total": null
},
"photos": [
{
"large": "https://img.holidu.com/images/7311b7d1-d35f-4a64-8f7f-89af73c259e8/l.jpg",
"medium": "https://img.holidu.com/images/7311b7d1-d35f-4a64-8f7f-89af73c259e8/m.jpg",
"overlay": false,
"high_res": "https://img.holidu.com/images/7311b7d1-d35f-4a64-8f7f-89af73c259e8/hr.jpg",
"thumbnail": "https://img.holidu.com/images/7311b7d1-d35f-4a64-8f7f-89af73c259e8/t.jpg"
},
{
"large": "https://img.holidu.com/images/7139915f-e37b-40a9-b7f1-4a59321837fc/l.jpg",
"medium": "https://img.holidu.com/images/7139915f-e37b-40a9-b7f1-4a59321837fc/m.jpg",
"overlay": false,
"high_res": "https://img.holidu.com/images/7139915f-e37b-40a9-b7f1-4a59321837fc/hr.jpg",
"thumbnail": "https://img.holidu.com/images/7139915f-e37b-40a9-b7f1-4a59321837fc/t.jpg"
}
],
"rating": {
"count": 9,
"value": 100
},
"details": {
"area": null,
"name": "Panoramic Views of Paris and Pool",
"bed_types": [
"BED_DOUBLE",
"BED_SLEEPING_COUCH"
],
"long_name": "Vacation apartment for 4 people",
"unit_name": null,
"pets_count": null,
"short_name": [
"4 Guests",
"Apartment"
],
"guests_count": 4,
"apartment_type": "APARTMENT",
"bedrooms_count": 2,
"short_description": null,
"apartment_type_name": "Apartment",
"apartment_type_title": "Apartment",
"alternative_long_name": null,
"sleeping_arrangements": {
"rooms": [
[],
[]
]
}
},
"group_id": "57639048",
"location": {
"lat": 48.834175,
"lng": 2.306001,
"name": "Paris, Ile de France",
"geo_hash": "u09tu3zptwnb",
"distance_to_search_region_center": {
"id": null,
"unit": "UNIT_MI",
"value": 0.9,
"format": "NUMBER_WITH_UNIT"
},
"distance_to_original_search_region_center": null
},
"position": 1,
"provider": {
"id": "HOMEAWAY",
"logo_url": "https://static.holidu.com/img/provider/logos/722/HOMEAWAY.png",
"legal_name": "HomeAway.com Inc.",
"short_name": "Vrbo",
"statistics": null,
"is_premium_partner": false
},
"meta_data": {
"multi_unit_data": {
"units": [],
"number_of_units": 0,
"part_of_multi_unit": false
}
},
"fuzzy_tags": [],
"amenities_v2": {
"AMENITY_IMPORTANT": [
{
"id": "KITCHEN",
"count": 1,
"group": "KITCHEN",
"value": "Kitchen",
"format": "STRING"
},
{
"id": "PARKING",
"count": 1,
"group": "PARKING",
"value": "Parking",
"format": "STRING"
}
]
},
"amenities_v3": null,
"is_available": null,
"routing_type": "OUTBOUND",
"holidu_rating": null,
"review_extract": null,
"missing_filters": [],
"ski_resort_names": [],
"external_group_id": null,
"cancellation_policy": {
"free_cancellation": {
"amount": null,
"percentage": null,
"until_date": "2027-02-27",
"days_before_arrival": 15
},
"light_cancellation": null
},
"is_express_bookable": false,
"is_instant_bookable": false,
"alternative_price_rates": []
}
],
"region": {
"id": 22458,
"name": "Paris",
"level": 16,
"prefix": "in",
"themes": [],
"availability": null,
"in_high_demand": false,
"booked_percentage": null,
"marketing_campaign_id": 53,
"total_number_of_offers": 8659
},
"currency": "USD",
"has_more": false,
"viewport": {
"ne": {
"lat": 48.902155961841345,
"lng": 2.469757441431284
},
"sw": {
"lat": 48.81557547021657,
"lng": 2.224121997132898
}
},
"page_size": 30,
"site_path": "/s/Paris--France?propertyType=VACATION_APARTMENT&amenities=POOL",
"sort_scope": "page",
"price_basis": "stay_total",
"total_pages": 1,
"removed_unrated": 0
},
"meta": {
"billable": true,
"endpoint_family": "rental_search"
},
"success": true
}Errors
Handle these documented responses before retrying or showing customer-facing failures.
Validation Error
A required query parameter is missing or invalid. This response is not billable.
{
"errors": {
"market": [
"The market is one of com, de, uk, fr."
]
},
"message": "The request validation failed"
}Service Unavailable
Holidu could not be reached, answered with an unexpected shape or returned a result that does not match the request. This response is not billable. Retry later.
{
"meta": {
"billable": false,
"retryable": true,
"endpoint_family": "rental_search"
},
"error": {
"code": "UPSTREAM_UNAVAILABLE",
"message": "The Holidu API is temporarily unavailable. Please retry."
},
"success": false
}Generate Code with AI
Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.
Try It Live
Test this endpoint in our interactive playground with real data.