TUI Group Hotel Availability API

openapi: 3.2.0
info:
  title: Meta-Search-Generic Hotel Availability API
  version: 0.3.1
  contact:
    email: pip-meta@tui.com
    name: meta.search.team
    url: https://source.tui/osp/pip/meta-layer/api/meta-search-generic-api
  description: The Meta-Search-Generic API that allows meta partners to access portfolio and offers information.
servers:
- url: https://pre-prod.api.tui/sales/pip/germany/tui/generic
- url: https://prod.api.tui/sales/pip/germany/tui/generic
tags:
- name: Hotel Availability
  description: Operations around hotel availability details
paths:
  /hotel_availability:
    post:
      tags:
      - Hotel Availability
      summary: Checks hotels availability
      description: Returns the hotel availability based on the provided criteria.
      operationId: getHotelAvailability
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HotelAvailabilityRequest'
      security:
      - OAuth2PreProdPublic: []
      - OAuth2ProdPublic: []
      responses:
        '200':
          description: Successfully updated the existing MetaSearchGeneric with the provided data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelAvailabilityResponse'
        '400':
          description: Bad Request - invalid input parameters or malformed request data.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Not Found - The requested resource could not be found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal Server Error - An unexpected occurred while processing the request.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    Problem:
      type: object
      properties:
        type:
          type: string
          format: uri-reference
          description: 'A URI reference that uniquely identifies the problem type only in the context of the provided API. Opposed to the specification in RFC-9457, it is neither recommended to be dereferenceable and point to a human-readable documentation nor globally unique for the problem type.

            '
          default: about:blank
          example: /some/uri-reference
        title:
          type: string
          description: 'A short summary of the problem type. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.

            '
          example: some title for the error situation
        status:
          type: integer
          format: int32
          description: 'The HTTP status code generated by the origin server for this occurrence of the problem.

            '
          minimum: 100
          exclusiveMaximum: 600
        detail:
          type: string
          description: 'A human readable explanation specific to this occurrence of the problem that is helpful to locate the problem and give advice on how to proceed. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.

            '
          example: some description for the error situation
        instance:
          type: string
          format: uri-reference
          description: 'A URI reference that identifies the specific occurrence of the problem, e.g. by adding a fragment identifier or sub-path to the problem type. May be used to locate the root of this problem in the source code.

            '
          example: /some/uri-reference#specific-occurrence-context
    Hotels:
      type: object
      required:
      - hotel_id
      - cheapest_offer
      properties:
        hotel_id:
          type: string
          description: The hotel ID.
          example: A1954871
        cheapest_offer:
          items:
            $ref: '#/components/schemas/Offer'
          description: The cheapest offer.
    Room:
      type: object
      required:
      - room_name
      - party
      - price_per_room
      - currency
      - breakfast_included
      - free_cancellation
      - local_tax
      - payment_type
      - room_code
      - rate_type
      - meal_code
      properties:
        room_name:
          type: string
          description: The room type name.
          example: double bedroom
        party:
          $ref: '#/components/schemas/Party'
        price_per_room:
          type: string
          format: decimal
          description: The price of the specific room
          example: '105.0'
        currency:
          type: string
          description: The currency code.
          example: EUR
        breakfast_included:
          type: boolean
          description: Whether breakfast is included.
          example: false
        free_cancellation:
          type: boolean
          description: Whether the room is free cancellation.
          example: false
        local_tax:
          type: string
          format: decimal
          description: The local tax.
          example: '0.0'
        payment_type:
          type: string
          description: The payment type.
          example: prepaid
        room_code:
          type: string
          description: The room code.
          example: adde03b2-9a69-45c7-85e3-ac63c9b247ca
        rate_type:
          type: string
          description: The rate type.
          example: DEFAULT
        meal_code:
          type: string
          description: The meal code.
          example: GT06-RO
        resort_fee:
          type: string
          format: decimal
          description: The resort fee.
          example: '0.0'
    Party:
      type: object
      required:
      - adults
      properties:
        adults:
          type: integer
          minimum: 1
          description: The number of adults.
          example: 2
        children_ages:
          type: array
          items:
            type: integer
          description: The ages of the children.
          example:
          - 5
          - 10
    Offer:
      type: object
      properties:
        total_price:
          type: string
          format: decimal
          description: The total price of the offer.
          example: '105.0'
        currency:
          type: string
          description: The currency code.
          example: EUR
        rooms:
          type: array
          items:
            $ref: '#/components/schemas/Room'
          description: The rooms.
        url:
          type: string
          description: The URL.
          example: Deeplink URL
      required:
      - total_price
      - currency
      - rooms
      - url
    HotelAvailabilityResponse:
      type: object
      required:
      - api_version
      - language
      - currency
      - hotel_ids
      - check_in_date
      - check_out_date
      - number_of_rooms
      - hotels
      properties:
        api_version:
          type: string
          description: The API current version.
          example: v1
        language:
          type: string
          description: The language in the API response.
          example: en_GB
        currency:
          type: string
          description: The currency code.
          example: EUR
        hotel_ids:
          type: array
          items:
            type: string
            example: A1954871
          description: The list of hotel IDs.
        check_in_date:
          type: string
          format: date
          description: The check-in date in the format YYYY-MM-DD.
          example: '2023-07-22'
        check_out_date:
          type: string
          format: date
          description: The check-out date in the format YYYY-MM-DD.
          example: '2023-07-30'
        number_of_rooms:
          type: integer
          description: The number of rooms.
          example: 1
        hotels:
          type: array
          items:
            $ref: '#/components/schemas/Hotels'
    HotelAvailabilityRequest:
      type: object
      required:
      - api_version
      - language
      - hotel_ids
      - check_in_date
      - check_out_date
      - number_of_rooms
      - party
      - currency
      properties:
        api_version:
          type: string
          description: The API current version.
          example: v1
        language:
          type: string
          description: The language in the API response.
          example: en_GB
        hotel_ids:
          type: array
          items:
            type: string
            example: A1954871
          description: The list of hotel IDs.
        check_in_date:
          type: string
          format: date
          description: The check-in date in the format YYYY-MM-DD.
          example: '2023-07-22'
        check_out_date:
          type: string
          format: date
          description: The check-out date in the format YYYY-MM-DD.
          example: '2023-07-30'
        number_of_rooms:
          type: integer
          description: The number of rooms.
          example: 1
        party:
          type: array
          items:
            $ref: '#/components/schemas/Party'
        currency:
          type: string
          description: The currency code.
          example: EUR
        rate_model:
          type: string
          description: The rate model - AI, GROSS, NET.
          example: AI
  securitySchemes:
    OAuth2PreProdPublic:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://pre-prod.api.tui/oauth2/token
          scopes: {}
    OAuth2ProdPublic:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://prod.api.tui/oauth2/token
          scopes: {}