openapi: 3.0.3
info:
  title: Starwood Hotel Search Availability API
  description: The Starwood Hotel Search API provided partners and developers with programmatic access to search Starwood Hotels & Resorts Worldwide's portfolio of over 1,300 hotel properties across approximately 100 countries. This API supported searching by geographic location (country, province, city) and travel dates, returning property details including name, address, category, best available rate, and Starwood Preferred Guest (SPG) points redemption options. Starwood was acquired by Marriott International in September 2016 and the SPG loyalty program was subsequently merged into Marriott Bonvoy in 2019.
  version: 1.0.0
  contact:
    name: Starwood Developer Support
    url: https://www.starwoodhotels.com
  termsOfService: https://www.starwoodhotels.com/corporate/terms.html
  license:
    name: Proprietary
    url: https://www.starwoodhotels.com/corporate/terms.html
servers:
- url: https://www.starwoodhotels.com/api
  description: Starwood Hotels API
tags:
- name: Availability
  description: Rate and availability operations
paths:
  /v1/hotels/{hotelId}/availability:
    get:
      operationId: getHotelAvailability
      summary: Get Hotel Availability
      description: Check room availability and current rates for a specific Starwood hotel property for given travel dates. Returns available room categories, rates, and SPG points options including cash-and-points combinations.
      tags:
      - Availability
      parameters:
      - name: hotelId
        in: path
        description: Unique Starwood hotel identifier
        required: true
        schema:
          type: string
          example: '1234'
      - name: arrivalDate
        in: query
        description: Check-in date in YYYY-MM-DD format
        required: true
        schema:
          type: string
          format: date
      - name: departureDate
        in: query
        description: Check-out date in YYYY-MM-DD format
        required: true
        schema:
          type: string
          format: date
      - name: adults
        in: query
        description: Number of adult guests
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 9
          default: 1
      responses:
        '200':
          description: Hotel availability and rates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelAvailabilityResponse'
        '404':
          description: Hotel not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: No availability for requested dates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    HotelAvailabilityResponse:
      type: object
      description: Hotel availability and rate information
      properties:
        hotelId:
          type: string
          description: Unique Starwood hotel identifier
          example: '1234'
        arrivalDate:
          type: string
          format: date
          description: Check-in date
        departureDate:
          type: string
          format: date
          description: Check-out date
        nights:
          type: integer
          description: Number of nights
          example: 3
        rooms:
          type: array
          description: Available room types and rates
          items:
            $ref: '#/components/schemas/RoomRate'
    Error:
      type: object
      description: Error response
      properties:
        code:
          type: string
          description: Error code
          example: INVALID_REQUEST
        message:
          type: string
          description: Human-readable error message
          example: Invalid arrival date format. Expected YYYY-MM-DD.
        details:
          type: array
          description: Additional error detail objects
          items:
            type: object
            properties:
              field:
                type: string
                description: Field name that caused the error
              message:
                type: string
                description: Field-specific error message
    RoomRate:
      type: object
      description: A room type with its available rates
      properties:
        roomTypeCode:
          type: string
          description: Room type code
          example: KING
        roomTypeName:
          type: string
          description: Room type name
          example: Deluxe King Room
        rateCode:
          type: string
          description: Rate plan code
          example: BAR
        rateName:
          type: string
          description: Rate plan name
          example: Best Available Rate
        pricePerNight:
          type: number
          format: double
          description: Rate per night in quoted currency
          example: 289.0
        totalPrice:
          type: number
          format: double
          description: Total price for the stay
          example: 867.0
        currency:
          type: string
          description: Currency code
          example: USD
        pointsPerNight:
          type: integer
          description: SPG Starpoints required for award night
          example: 12000
        availability:
          type: string
          description: Availability status
          enum:
          - AVAILABLE
          - LIMITED
          - UNAVAILABLE
          example: AVAILABLE