Traveloka 2.1 Search - HotelList API

openapi: 3.2.0
info:
  title: Traveloka Atlas 2.1 Search - HotelList API
  version: ''
  description: 'Traveloka Specification API for Accommodation Provider


    **General Notes**

    * Please ensure that the endpoint is configured to connect using **HTTPS via port 443.**

    * For fields with type "String", if there''s no value, do not return empty string (e.g.'
servers:
- url: http://localhost:8080
  description: Generated server url
security: []
tags:
- name: 2.1 Search - HotelList
paths:
  /hotel-list:
    post:
      tags:
      - 2.1 Search - HotelList
      summary: Search for hotels
      description: This operation is for Traveloka to search for hotels based on the provided criteria.
      operationId: hotelList
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HotelListSearchRequest'
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelListSearchResponse'
              examples:
                Not available:
                  summary: Search request is not available
                  description: Not available
                  value:
                    requestId: requestId
                Http Status OK with error:
                  summary: Object response when http status is 200 but contains error
                  description: Http Status OK with error
                  value:
                    requestId: requestId
                    error:
                      errorId: RATE_UNAVAILABLE
                      errorMessage: Rate is unavailable
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelListSearchErrorResponse'
              examples:
                Error 400 example:
                  summary: This example is using INVALID_BOOKING_WINDOW error
                  description: Error 400 example
                  value:
                    requestId: requestId
                    error:
                      errorId: INVALID_BOOKING_WINDOW
                      errorMessage: Invalid booking window
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelListSearchErrorResponse'
              examples:
                Error 401 example:
                  summary: This example is using AUTHENTICATION_FAILED error
                  description: Error 401 example
                  value:
                    requestId: requestId
                    error:
                      errorId: AUTHENTICATION_FAILED
                      errorMessage: Invalid username/password
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelListSearchErrorResponse'
              examples:
                Error 429 example:
                  summary: This example is using TOO_MANY_REQUESTS error
                  description: Error 429 example
                  value:
                    requestId: requestId
                    error:
                      errorId: TOO_MANY_REQUESTS
                      errorMessage: Too many requests. Please try again.
        '500':
          description: Something went wrong
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelListSearchErrorResponse'
              examples:
                Error 500 example:
                  summary: This example is using UNKNOWN_SERVER_ERROR error
                  description: Error 500 example
                  value:
                    requestId: requestId
                    error:
                      errorId: UNKNOWN_SERVER_ERROR
                      errorMessage: Unknown server error
      servers:
      - url: http://localhost:8080
        description: Generated server url
components:
  schemas:
    HotelRoomSize:
      required:
      - size
      - unit
      type: object
      properties:
        size:
          type: number
          description: Size of the room
          format: double
          example: 42
        isSizeIncludingTerrace:
          type: boolean
        unit:
          type: string
          description: Unit of measurement for the room size
          enum:
          - SQUARE_METER
          - SQUARE_FOOT
          - UNKNOWN
        description:
          type: string
      description: Room size
    HotelRoomRate:
      required:
      - currency
      - fees
      - taxes
      - totalFare
      type: object
      properties:
        currency:
          type: string
          description: Currency code, e.g. IDR, USD
          example: IDR
        totalFare:
          type: number
          description: Total fare (including taxes, fees, and commission). If two rooms are requested in the specs, this totalFare will be for two rooms.
          format: double
          example: 1000000
        taxes:
          type: number
          description: Total taxes amount
          format: double
          example: 100000
        fees:
          type: number
          description: Total fees amount
          format: double
          example: 50000
    AdditionalFees:
      type: object
      properties:
        mandatoryFee:
          allOf:
          - $ref: '#/components/schemas/ChargeItem'
          - description: Mandatory fees are collected by the property at check-in or check-out.
        mandatoryTax:
          allOf:
          - $ref: '#/components/schemas/ChargeItem'
          - description: Mandatory taxes are collected by the property at check-in or check-out.
        resortFee:
          allOf:
          - $ref: '#/components/schemas/ChargeItem'
          - description: Resort fees are charged for amenities and extras and collected by the property at check-in or check-out.
        countryTaxFee:
          allOf:
          - $ref: '#/components/schemas/ChargeItem'
          - description: Country tax fee is collected by the property at check-in or check-out.
    ChargeItem:
      required:
      - amount
      - currency
      type: object
      properties:
        currency:
          type: string
          description: Currency of the charge item, e.g., USD, IDR
          example: USD
        amount:
          type: number
          description: Amount of the charge item
          format: double
          example: 100
    HotelListSearchResponse:
      required:
      - results
      type: object
      properties:
        requestId:
          type: string
          description: Request ID for this search request
          example: 928827d7-b847-495f-9592-f207df896ac4
        results:
          type: array
          description: List of hotels with rooms and inventory that match the search criteria
          items:
            $ref: '#/components/schemas/HotelWithRoomWithInventoryResponse'
        error:
          allOf:
          - $ref: '#/components/schemas/Error'
          - description: For complete error enums, please check on FAQ > Error Object
    HotelListHotelRoom:
      required:
      - beds
      - occupancyPolicy
      - providerHotelRoomId
      - rateType
      type: object
      properties:
        providerHotelRoomId:
          type: string
          description: Provider hotel room ID
          example: '1234567890'
        rateType:
          type: string
          description: Hotel Rate Type
          enum:
          - PAY_NOW
          - PAY_AT_PROPERTY
        description:
          type: string
          description: Room description in English
          example: A spacious room with a king-sized bed and a beautiful view of the city.
        caption:
          type: string
          description: Room caption in English
          example: Deluxe Room
        occupancyPolicy:
          allOf:
          - $ref: '#/components/schemas/HotelRoomOccupancyPolicy'
          - description: Room occupancy policy
        size:
          $ref: '#/components/schemas/HotelRoomSize'
        beds:
          $ref: '#/components/schemas/HotelBeds'
    HotelInventory:
      required:
      - currency
      - hotelRoomName
      - maxExtraBeds
      - numChargedRooms
      - numRemainingRooms
      - providerOriginalRate
      - providerRecommendedSellingRate
      type: object
      properties:
        numRemainingRooms:
          type: integer
          description: Number of Remaining Bookable Room
          format: int32
          example: 4
        maxExtraBeds:
          type: integer
          description: Maximum number of extra beds for the room
          format: int32
          example: 2
        currency:
          type: string
          description: Currency info
          example: IDR
        providerRecommendedSellingRate:
          allOf:
          - $ref: '#/components/schemas/HotelRoomRate'
          - description: Recommended price for this room type in currency provided by the request
        providerOriginalRate:
          $ref: '#/components/schemas/HotelRoomRate'
        additionalFees:
          $ref: '#/components/schemas/AdditionalFees'
        hotelRoomName:
          type: string
          description: Hotel room name of the cheapest room
          example: Deluxe Room
        numChargedRooms:
          type: integer
          description: Number of room being charged. If two rooms are requested in the request spec, this should return 2 and the price will be for two rooms.
          format: int32
          example: 2
        hotelPromoType:
          $ref: '#/components/schemas/HotelPromoType'
    HotelBeds:
      required:
      - bedType
      - numBeds
      type: object
      properties:
        numBeds:
          type: integer
          description: Number of beds in the room
          format: int32
          example: 2
        bedType:
          type: string
          description: Type of the bed
          enum:
          - SINGLE
          - DOUBLE
          - TWIN
          - QUEEN
          - KING
          - ONE_SINGLE_BED
          - ONE_DOUBLE_BED
          - ONE_QUEEN_BED
          - ONE_KING_BED
          - ONE_DOUBLE_BED_AND_ONE_SINGLE_BED
          - ONE_DOUBLE_BED_AND_TWO_SINGLE_BED
          - ONE_DOUBLE_BED_AND_FOUR_SINGLE_BED
          - ONE_DOUBLE_BED_OR_TWO_SINGLE_BED
          - TWO_SINGLE_BED
          - TWO_DOUBLE_BED
          - TWO_QUEEN_BED
          - TWO_KING_BED
          - TWO_DOUBLE_AND_TWO_SINGLE_BED
          - THREE_SINGLE_BED
          - THREE_DOUBLE_BED
          - DOUBLE_SINGLE_AND_SOFA_BED
          - CAPSULE_BED
          - BUNK_BED
          - UNKNOWN
        description:
          type: string
          description: Beds description
          example: Single Beds
    Error:
      type: object
      properties:
        errorId:
          type: string
        errorMessage:
          type: string
    HotelListSearchRequest:
      required:
      - cache
      - checkInDate
      - checkOutDate
      - currency
      - numAdults
      - numChildren
      - numRooms
      - providerHotelIds
      type: object
      properties:
        requestId:
          type: string
          description: Request ID for this search request
          example: 928827d7-b847-495f-9592-f207df896ac4
        providerHotelIds:
          type: array
          description: List of provider hotel IDs to be searched. We will search at maximum 1000 hotels per search.
          example:
          - '1234567890'
          - 0987654321
          items:
            type: string
            description: List of provider hotel IDs to be searched. We will search at maximum 1000 hotels per search.
            example: '["1234567890","0987654321"]'
        rateTypes:
          type: array
          description: Hotel Rate Type.
          items:
            type: string
            description: Hotel Rate Type.
            enum:
            - PAY_NOW
            - PAY_AT_PROPERTY
        hotelRatePlanType:
          type: string
          description: Hotel Rate Plan Type.
          enum:
          - RETAIL
          - MOBILE
          - PRIVATESALE
          - LAST_MINUTE
          - BUDGET_ROOMS
          - PACKAGE
          - CAMPAIGN
          - CROSS_SELL
          - CORPORATE
          - STATIC
          - GROWTH_MARKET
        sourceMarket:
          type: string
          description: Country ID to indicate the source (customer) search market. For example, providers have option to set special price for certain nationality when booking property located overseas.
          example: ID
        numRooms:
          type: integer
          description: Number of rooms to be booked in this search request
          format: int32
          example: 1
        numAdults:
          type: integer
          description: Number of adults (total adults per booking, not total adult per room)
          format: int32
          example: 2
        numChildren:
          type: integer
          description: Number of children (total children per booking, not total children per room)
          format: int32
          example: 1
        childrenAges:
          type: array
          description: Mandatory if numChildren > 0
          example:
          - 5
          items:
            type: integer
            description: Mandatory if numChildren > 0
            format: int32
        checkInDate:
          type: string
          description: Check-in date in yyyy-MM-dd format
          example: '2023-10-01'
        checkOutDate:
          type: string
          description: Check-out date in yyyy-MM-dd format
          example: '2023-10-02'
        currency:
          type: string
          description: Currency code for the search request, e.g. IDR, USD
          example: IDR
        locale:
          type: string
          description: Locale for the search request, e.g. en_US, id_ID
          example: en_ID
        cache:
          type: boolean
          description: 'Indicates whether to return the cached search result or not.


            If true → return cached rates.


            If false → return latest rates.

            '
          example: false
    HotelListSearchErrorResponse:
      required:
      - error
      type: object
      properties:
        requestId:
          type: string
          description: Request ID for this search request
          example: 928827d7-b847-495f-9592-f207df896ac4
        error:
          allOf:
          - $ref: '#/components/schemas/Error'
          - description: For complete error enums, please check on FAQ > Error Object
    HotelWithRoomWithInventoryResponse:
      required:
      - hotelInventory
      - providerHotelId
      - rooms
      type: object
      properties:
        providerHotelId:
          type: string
          description: Provider hotel ID
          example: '1234567890'
        hotelInventory:
          allOf:
          - $ref: '#/components/schemas/HotelInventory'
          - description: Data for the cheapest room of the hotel
        rooms:
          type: array
          description: List of rooms in the hotel
          items:
            $ref: '#/components/schemas/HotelListHotelRoom'
    HotelRoomOccupancyPolicy:
      required:
      - maxOccupancy
      type: object
      properties:
        maxOccupancy:
          type: integer
          description: Return exactly the number of adults that were used in the search specification
          format: int32
          example: 2
        maxChildOccupancy:
          type: integer
          description: Return exactly the number of children that were used in the search specification
          format: int32
          example: 2
        maxInfantOccupancy:
          type: integer
          description: Return exactly the number of children that were used in the search specification
          format: int32
          example: 1
        maxExtraBeds:
          type: integer
          description: Maximum number of extra beds in the room based on user specification
          format: int32
          example: 1
      description: Room occupancy policy
    HotelPromoType:
      type: object
      properties:
        promoType:
          type: string
          description: Type of the hotel promo
          enum:
          - SALE
          - EARLY_BIRD
          - LAST_MINUTE
          - UNKNOWN
        promoDescription:
          type: string
          description: Description of the hotel promo
      description: Promotion details (if applicable)
  securitySchemes:
    basicAuth:
      type: http
      description: 'Custom Basic Auth format:

        - Format: username:password

        - Encode with Base64

        - Send in header: Authorization: Basic base64(username:password)

        '
      scheme: basic
x-tagGroups:
- name: Traveloka Atlas API (1.0)
  tags:
  - 1.1 Content - Hotel & Room
  - 2.1 Search - HotelList
  - 2.2 Search - RoomList
  - 2.3 Search - BulkRoomList
  - 3.1 Booking - Book
  - 3.2 Booking - IssueCheck
  - 3.3 Booking - Issue
  - 3.4 Booking - BookingSummary
  - 3.5 Booking - Cancel