Holidu Search API
The Search API from Holidu — 1 operation(s) for search.
OpenAPI Specification
openapi: 3.0.3
info:
title: Affiliate Apartment Search API
version: 1.1.0
servers:
- url: https://external-api.holidu.com
tags:
- name: Search
paths:
/search:
post:
operationId: search
summary: Search for offers based on the provided criteria
description: Retrieve a paginated list of offers matching specified filtering criteria, ranked by relevance. If dates are provided, only available offers for those dates are returned with exact pricing. Each offer includes basic property information.
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
pageIndex:
type: integer
minimum: 0
maximum: 10000
description: Zero-based page index
pageSize:
type: integer
minimum: 1
maximum: 50
description: Number of results per page
searchTerm:
type: string
locationBoundingBox:
type: object
properties:
neLat:
type: number
minimum: -90
maximum: 90
neLng:
type: number
minimum: -180
maximum: 180
swLat:
type: number
minimum: -90
maximum: 90
swLng:
type: number
minimum: -180
maximum: 180
required:
- neLat
- neLng
- swLat
- swLng
additionalProperties: false
description: Bounding box of the search location. Overrides the searchTerm parameter
checkin:
type: string
format: date
description: Check-in date in ISO format YYYY-MM-DD
checkout:
type: string
format: date
description: Check-out date in ISO format YYYY-MM-DD
adults:
type: integer
minimum: 1
maximum: 50
description: Number of adult guests
children:
type: integer
minimum: 0
maximum: 50
description: Number of child guests
childrenAges:
type: array
items:
type: integer
minimum: 0
maximum: 17
minItems: 1
maxItems: 50
description: Ages of child guests, defaults to 10 if not specified
bedrooms:
type: integer
minimum: 1
description: Number of bedrooms
locale:
type: string
pattern: ^[a-z]{2}-[A-Z]{2}$
description: Locale code in format ISO 639-1 + ISO 3166-1 alpha-2, e.g. "en-US"
currency:
type: string
pattern: ^[A-Z]{3}$
description: Currency code in ISO 4217 format, e.g. "USD"
propertyTypes:
type: array
items:
type: string
minLength: 1
maxLength: 80
description: List of property types
propertyIds:
type: array
items:
type: string
minLength: 1
maxLength: 80
minItems: 1
maxItems: 50
description: List of property IDs to search for specifically (max 50)
facilities:
type: array
items:
type: string
description: List of facilities
extras:
type: array
items:
type: string
enum:
- description
- photos
- facilities
description: 'Extra fields to include in the response. Supported values: description, photos, facilities'
salesChannelId:
type: string
minLength: 1
maxLength: 80
description: Only for special cases, consult Holidu
domainId:
type: integer
minimum: 1
maximum: 99999
description: Only for special cases, consult Holidu
required:
- adults
- children
- locale
- currency
additionalProperties: false
parameters: []
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
metadata:
type: object
properties:
totalCount:
type: integer
description: Total number of results matching the search criteria
required:
- totalCount
additionalProperties: false
items:
type: array
items:
type: object
properties:
id:
type: string
minLength: 1
description:
type: string
nullable: true
description: Short text description of the offer
photos:
type: array
items:
type: object
properties:
thumbnail:
type: string
format: uri
medium:
type: string
format: uri
large:
type: string
format: uri
required:
- thumbnail
- medium
- large
additionalProperties: false
nullable: true
url:
type: string
area:
type: object
properties:
value:
type: number
minimum: 0
unit:
type: string
enum:
- UNIT_SM
- UNIT_SF
description: Unit of the area. Either UNIT_SM (square meters) of UNIT_SF (square feet)
required:
- value
- unit
additionalProperties: false
nullable: true
bedroomCount:
type: integer
nullable: true
bathroomCount:
type: integer
nullable: true
guestCount:
type: integer
description: Number of guests the offer can accommodate
title:
type: string
propertyType:
type: object
properties:
id:
type: string
title:
type: string
minLength: 1
maxLength: 80
required:
- id
- title
additionalProperties: false
facilities:
type: array
items:
type: object
properties:
id:
type: string
title:
type: string
minLength: 2
maxLength: 80
group:
type: string
required:
- id
- title
- group
additionalProperties: false
nullable: true
petsAllowed:
type: boolean
location:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 350
distance:
type: string
nullable: true
description: Distance in meters to the center of search region if specified, otherwise null
postalCode:
type: string
nullable: true
description: Postal code, can be null if not shared by the provider
city:
type: string
nullable: true
description: City name, can be null if not shared by the provider
coordinates:
type: object
properties:
lat:
type: number
minimum: -90
maximum: 90
lng:
type: number
minimum: -180
maximum: 180
required:
- lat
- lng
additionalProperties: false
required:
- name
- distance
- postalCode
- city
- coordinates
additionalProperties: false
nullable: true
price:
anyOf:
- type: object
properties:
currency:
type: string
description: Currency code in ISO 4217 format, e.g. "USD"
daily:
type: number
total:
type: number
nights:
type: integer
discountAmount:
type: number
minimum: 0
nullable: true
description: Absolute discount amount in given currency
discountPercentage:
type: number
nullable: true
totalBeforeDiscount:
type: number
nullable: true
dailyBeforeDiscount:
type: number
nullable: true
required:
- currency
- daily
- total
- nights
- discountAmount
- discountPercentage
- totalBeforeDiscount
- dailyBeforeDiscount
additionalProperties: false
description: Price information for the offer for a given travel dates
- type: object
properties:
currency:
type: string
description: Currency code in ISO 4217 format, e.g. "USD"
daily:
type: number
required:
- currency
- daily
additionalProperties: false
description: Minimal daily price for a property, doesn't depend on travel dates
description: Price information for the offer, either for a given travel dates or as a starting price
cancellationPolicy:
type: object
properties:
type:
type: string
enum:
- FREE_CANCELLATION
- LIGHT_CANCELLATION
required:
- type
additionalProperties: false
nullable: true
rating:
type: object
properties:
value:
type: number
minimum: 0
maximum: 10
count:
type: integer
minimum: 0
required:
- value
- count
additionalProperties: false
nullable: true
licenseId:
type: string
nullable: true
required:
- id
- description
- photos
- url
- area
- bedroomCount
- bathroomCount
- guestCount
- title
- propertyType
- facilities
- petsAllowed
- location
- price
- cancellationPolicy
- rating
- licenseId
additionalProperties: false
errors:
type: array
items:
type: object
properties:
apartmentId:
type: string
code:
type: number
message:
type: string
required:
- apartmentId
- code
- message
additionalProperties: false
required:
- metadata
- items
additionalProperties: false
default:
$ref: '#/components/responses/error'
tags:
- Search
components:
responses:
error:
description: Error response
content:
application/json:
schema:
type: object
properties:
message:
type: string
code:
type: string
issues:
type: array
items:
type: object
properties:
message:
type: string
required:
- message
additionalProperties: false
required:
- message
- code
additionalProperties: false
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Holidu authenticates to the affiliate using an OAuth 2.0 Bearer Token ([RFC 6750](https://www.rfc-editor.org/rfc/rfc6750)). Token exchange details are agreed upon during onboarding.