openapi: 3.0.3
info:
  title: Starwood Hotel Search Availability Hotels 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: Hotels
  description: Hotel search and property operations
paths:
  /v1/hotels/search:
    get:
      operationId: searchHotels
      summary: Search Hotels
      description: Search Starwood hotel properties by geographic location and travel dates. Returns a list of available hotels with rates, property details, and SPG points redemption options.
      tags:
      - Hotels
      parameters:
      - name: country
        in: query
        description: Two-letter ISO country code (e.g., US, CN, FR)
        required: true
        schema:
          type: string
          pattern: ^[A-Z]{2}$
          example: US
      - name: province
        in: query
        description: Province or state code within the country (e.g., USIL, CNHP)
        required: false
        schema:
          type: string
          example: USIL
      - name: city
        in: query
        description: City name for hotel search
        required: false
        schema:
          type: string
          example: Chicago
      - name: arrivalDate
        in: query
        description: Check-in date in YYYY-MM-DD format
        required: true
        schema:
          type: string
          format: date
          example: '2026-06-15'
      - name: departureDate
        in: query
        description: Check-out date in YYYY-MM-DD format
        required: true
        schema:
          type: string
          format: date
          example: '2026-06-18'
      - name: adults
        in: query
        description: Number of adult guests
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 9
          default: 1
      - name: brand
        in: query
        description: Filter by Starwood brand code
        required: false
        schema:
          type: string
          enum:
          - SH
          - WI
          - WH
          - SR
          - LM
          - FP
          - AL
          - EL
          - TP
          - DH
          example: WI
      - name: categoryMin
        in: query
        description: Minimum SPG category for luxury filtering (1-7)
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 7
      responses:
        '200':
          description: Successful hotel search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelSearchResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No hotels found for given criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    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
    Hotel:
      type: object
      description: A Starwood hotel property
      properties:
        id:
          type: string
          description: Unique Starwood hotel identifier
          example: '1234'
        name:
          type: string
          description: Full hotel property name
          example: The Westin Michigan Avenue Chicago
        brand:
          type: string
          description: Starwood brand code
          example: WI
        brandName:
          type: string
          description: Full Starwood brand name
          example: Westin
        category:
          type: integer
          description: SPG category level (1-7, higher is more luxury)
          minimum: 1
          maximum: 7
          example: 4
        thumbnail:
          type: string
          description: URL to the hotel thumbnail image
          format: uri
          example: https://www.starwoodhotels.com/images/hotels/1234/thumb.jpg
        address:
          type: string
          description: Street address
          example: 909 N. Michigan Ave.
        city:
          type: string
          description: City name
          example: Chicago
        state:
          type: string
          description: State or province code
          example: IL
        country:
          type: string
          description: Two-letter ISO country code
          example: US
        zipcode:
          type: string
          description: Postal code
          example: '60611'
        phone:
          type: string
          description: Hotel front desk phone number
          example: +1-312-943-7200
        fax:
          type: string
          description: Hotel fax number
          example: +1-312-943-7201
        description:
          type: string
          description: Hotel property description
          example: A landmark Michigan Avenue hotel with breathtaking views of Lake Michigan and the Chicago skyline.
        latitude:
          type: number
          format: double
          description: Geographic latitude
          example: 41.8981
        longitude:
          type: number
          format: double
          description: Geographic longitude
          example: -87.624
        bestRate:
          type: number
          format: double
          description: Best available rate per night in USD
          example: 289.0
        currency:
          type: string
          description: Currency code for rates
          example: USD
        redeemPoints:
          type: integer
          description: SPG Starpoints required for award redemption per night
          example: 12000
        redeemCashPoints:
          type: integer
          description: Starpoints required for cash-and-points redemption
          example: 6000
        amenities:
          type: array
          description: List of hotel amenity codes
          items:
            type: string
          example:
          - POOL
          - FITNESS
          - SPA
          - WIFI
          - RESTAURANT
          - BUSINESS_CENTER
    HotelSearchResponse:
      type: object
      description: Response containing a list of matching hotels
      properties:
        hotels:
          type: array
          description: List of matching hotel properties
          items:
            $ref: '#/components/schemas/Hotel'
        totalCount:
          type: integer
          description: Total number of matching hotels
          example: 12
        searchParameters:
          type: object
          description: Echo of the search parameters used
          properties:
            country:
              type: string
              example: US
            city:
              type: string
              example: Chicago
            arrivalDate:
              type: string
              format: date
            departureDate:
              type: string
              format: date