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.