openapi: 3.0.0
info:
  title: Expedia Hotels API
  description: |
    Search hotels and other stays on Expedia for a place and dates, with guests, rooms, star, rating, property type, amenity, nightly price and free cancellation filters, sorting and pages.
    Each property returns its guest rating and review count, location, amenities, badges, its nightly price and the stay's total with taxes and fees, and whether it is fully refundable or VIP Access.

    **Cross-linking**: For Google Hotels, Kayak or Skyscanner prices in the same place, use the Google Hotels API, the Kayak Hotels API or the Skyscanner Hotels API.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Expedia Hotels Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Engine used to retrieve the results.
          schema:
            type: string
            enum: ["expedia_hotels"]
        - name: q
          in: query
          required: true
          description: City, region, neighborhood, landmark, airport or hotel name with at least one letter or digit, searched as the place Expedia suggests for it; a hotel name searches that hotel's city.
          schema:
            type: string
            maxLength: 100
        - name: check_in_date
          in: query
          required: true
          description: 'Check-in date, from today. Format: YYYY-MM-DD'
          schema:
            type: string
            format: date
        - name: check_out_date
          in: query
          required: true
          description: 'Check-out date, after check_in_date and up to 500 days ahead. Format: YYYY-MM-DD'
          schema:
            type: string
            format: date
        - name: adults
          in: query
          required: false
          description: Number of adults, at least one per room and at most 14 guests per room with the children.
          schema:
            type: integer
            minimum: 1
            maximum: 112
            default: 2
        - name: children_ages
          in: query
          required: false
          description: Comma-separated ages of the children, each from 0 to 17.
          schema:
            type: string
            pattern: '^\s*\d{1,2}\s*(?:,\s*\d{1,2}\s*)*$'
        - name: rooms
          in: query
          required: false
          description: Number of rooms, with the guests spread over them. Prices cover every room and night.
          schema:
            type: integer
            minimum: 1
            maximum: 8
            default: 1
        - name: sort_by
          in: query
          required: false
          description: Order of the properties.
          schema:
            type: string
            enum: ["relevance", "lowest_price", "highest_price", "highest_class"]
            default: "relevance"
        - name: hotel_class
          in: query
          required: false
          description: Comma-separated star ratings to keep, from 1 to 5.
          schema:
            type: string
            pattern: '^\s*[1-5]\s*(?:,\s*[1-5]\s*)*$'
        - name: rating
          in: query
          required: false
          description: Lowest guest rating to keep, out of 10.
          schema:
            type: string
            enum: ["7", "8", "9"]
        - name: property_types
          in: query
          required: false
          description: Comma-separated property types to keep.
          schema:
            type: string
            pattern: '^\s*(?:hotel|hostel|aparthotel|bed_and_breakfast|resort|guest_house|apartment|house|villa|cabin|cottage|chalet|lodge|residence|palace|country_house|farm_stay|houseboat|boat|rv|cruise)\s*(?:,\s*(?:hotel|hostel|aparthotel|bed_and_breakfast|resort|guest_house|apartment|house|villa|cabin|cottage|chalet|lodge|residence|palace|country_house|farm_stay|houseboat|boat|rv|cruise)\s*)*$'
        - name: amenities
          in: query
          required: false
          description: Comma-separated amenities every property must have.
          schema:
            type: string
            pattern: '^\s*(?:breakfast_included|all_inclusive|pay_later|vip_access|free_airport_shuttle|wifi|fitness_center|air_conditioning|pool|spa|hot_tub|kitchen|washer_dryer|restaurant|pet_friendly|crib|outdoor_space|ev_charger|parking)\s*(?:,\s*(?:breakfast_included|all_inclusive|pay_later|vip_access|free_airport_shuttle|wifi|fitness_center|air_conditioning|pool|spa|hot_tub|kitchen|washer_dryer|restaurant|pet_friendly|crib|outdoor_space|ev_charger|parking)\s*)*$'
        - name: price_min
          in: query
          required: false
          description: Lowest nightly price to keep, in US dollars.
          schema:
            type: integer
            minimum: 0
            maximum: 100000
        - name: price_max
          in: query
          required: false
          description: Highest nightly price to keep, in US dollars, above price_min.
          schema:
            type: integer
            minimum: 0
            maximum: 100000
        - name: free_cancellation
          in: query
          required: false
          description: Keeps only fully refundable properties.
          schema:
            type: boolean
        - name: page
          in: query
          required: false
          description: Page of results, with up to 50 properties per page.
          schema:
            type: integer
            minimum: 1
            maximum: 40
            default: 1
        - name: zero_retention
          in: query
          required: false
          description: Set to true to disable logging and persistent storage for this request. Enterprise plans only.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Successful response. A search Expedia answers without properties carries an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      required: [search_metadata, search_parameters]
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        search_information:
          $ref: '#/components/schemas/SearchInformation'
        properties:
          type: array
          description: Properties on the requested page, in the order asked for.
          items:
            $ref: '#/components/schemas/Property'
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Message explaining why the search has no properties.
    SearchMetadata:
      type: object
      required: [status, created_at]
      properties:
        id:
          type: string
          description: "Unique identifier for the search request"
        status:
          type: string
          description: "Status of the search request"
        created_at:
          type: string
          format: date-time
          description: "Timestamp when the search was created"
        request_time_taken:
          type: number
          description: "Time taken to make the request in seconds"
        parsing_time_taken:
          type: number
          description: "Time taken to parse the results in seconds"
        total_time_taken:
          type: number
          description: "Total time taken for the search in seconds"
        request_url:
          type: string
          description: "Expedia URL for this search"
        html_url:
          type: string
          description: "URL to view HTML results"
        json_url:
          type: string
          description: "URL to view JSON results"
    SearchParameters:
      type: object
      required: [engine, q, check_in_date, check_out_date]
      properties:
        engine:
          type: string
          description: Engine used for the search.
        q:
          type: string
          description: Place or hotel searched.
        check_in_date:
          type: string
          description: Check-in date.
        check_out_date:
          type: string
          description: Check-out date.
        adults:
          type: integer
          description: Number of adults.
        children_ages:
          type: string
          description: Ages of the children.
        rooms:
          type: integer
          description: Number of rooms.
        sort_by:
          type: string
          description: Order of the properties.
        hotel_class:
          type: string
          description: Star ratings kept.
        rating:
          type: string
          description: Lowest guest rating kept.
        property_types:
          type: string
          description: Property types kept.
        amenities:
          type: string
          description: Amenities every property has.
        price_min:
          type: integer
          description: Lowest nightly price kept, in US dollars.
        price_max:
          type: integer
          description: Highest nightly price kept, in US dollars.
        free_cancellation:
          type: boolean
          description: Whether only fully refundable properties are kept.
        page:
          type: integer
          description: Page of results.
    SearchInformation:
      type: object
      required: [total_results, check_in_date, check_out_date, nights, currency]
      properties:
        total_results:
          type: integer
          description: Number of properties Expedia counts for the search.
        destination:
          type: string
          description: Full name of the place searched.
        destination_type:
          type: string
          description: Kind of place searched, such as city, neighborhood, airport or poi.
        check_in_date:
          type: string
          description: Check-in date searched.
        check_out_date:
          type: string
          description: Check-out date searched.
        nights:
          type: integer
          description: Number of nights searched.
        currency:
          type: string
          description: Currency of every price.
    Property:
      type: object
      required: [position, property_id, title, link, is_free_cancellation, is_vip_access, images]
      properties:
        position:
          type: integer
          description: Position of the property on the page, starting at 1.
        property_id:
          type: string
          description: Expedia's id for the property.
        title:
          type: string
          description: Name of the property.
        link:
          type: string
          description: Expedia page of the property.
        extracted_hotel_class:
          type: integer
          description: Star rating of the property.
        location:
          type: string
          description: Area or city where the property is.
        gps_coordinates:
          $ref: '#/components/schemas/GpsCoordinates'
        rating:
          type: number
          description: Guest rating out of 10.
        max_rating:
          type: integer
          description: Highest possible guest rating.
        rating_word:
          type: string
          description: Word Expedia gives the guest rating, such as Exceptional.
        reviews:
          type: integer
          description: Number of guest reviews behind the rating.
        badges:
          type: array
          description: Badges Expedia shows on the property, such as VIP Access or a discount.
          items:
            type: string
        amenities:
          type: array
          description: Amenities Expedia highlights for the property.
          items:
            type: string
        price_per_night:
          $ref: '#/components/schemas/Price'
        total_price:
          $ref: '#/components/schemas/TotalPrice'
        is_free_cancellation:
          type: boolean
          description: Whether the property is fully refundable.
        is_vip_access:
          type: boolean
          description: Whether the property is a VIP Access property.
        images:
          type: array
          description: Photos of the property.
          items:
            $ref: '#/components/schemas/Image'
    Price:
      type: object
      required: [price, extracted_price]
      properties:
        price:
          type: string
          description: Nightly price as Expedia shows it.
        extracted_price:
          type: number
          description: Nightly price as a number.
    TotalPrice:
      type: object
      required: [price, extracted_price]
      properties:
        price:
          type: string
          description: Price of the stay with taxes and fees, for every room and night searched.
        extracted_price:
          type: number
          description: Price of the stay as a number.
        original_price:
          type: string
          description: Price of the stay before the discount.
        extracted_original_price:
          type: number
          description: Price of the stay before the discount as a number.
    Image:
      type: object
      required: [thumbnail, original]
      properties:
        thumbnail:
          type: string
          description: Cropped version of the photo.
        original:
          type: string
          description: Full-size photo.
        description:
          type: string
          description: Description of the photo.
    GpsCoordinates:
      type: object
      required: [latitude, longitude]
      properties:
        latitude:
          type: number
          description: Latitude of the property.
        longitude:
          type: number
          description: Longitude of the property.
    Pagination:
      type: object
      required: [current]
      properties:
        current:
          type: integer
          description: Current page.
        total_pages:
          type: integer
          description: Number of pages of results.
        next:
          type: integer
          description: Next page.
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong