> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rovemiles.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve a list of hotels

> Returns a list of hotels based on search criteria. This endpoint provides hotel metadata including names, addresses, ratings, and amenities.



## OpenAPI

````yaml https://api.staging.rovemiles.com/functions/v1/openapi get /hotels/list
openapi: 3.0.3
info:
  title: Rove Miles API
  version: 0.1.0
  description: Data Utils, Flights, Hotels & Miles endpoints.
servers:
  - url: https://api.staging.rovemiles.com/functions/v1
security:
  - bearerAuth: []
tags:
  - name: Data
    description: Operations related to reference data like airports and places
  - name: Flights
    description: Operations related to flight search and booking
  - name: Hotels
    description: Operations related to hotel search and booking
  - name: Miles
    description: Operations related to miles and points management
  - name: Deals
    description: Operations related to special offers and promotions for flights and hotels
paths:
  /hotels/list:
    get:
      tags:
        - Hotels
      summary: Retrieve a list of hotels
      description: >-
        Returns a list of hotels based on search criteria. This endpoint
        provides hotel metadata including names, addresses, ratings, and
        amenities.
      parameters:
        - name: placeId
          in: query
          required: false
          schema:
            type: string
          description: Place ID obtained from the /data/places search endpoint
        - name: countryCode
          in: query
          required: false
          schema:
            type: string
            pattern: ^[A-Z]{2}$
          description: Country code in ISO-2 format (e.g., 'US')
        - name: cityName
          in: query
          required: false
          schema:
            type: string
          description: Name of the city
        - name: hotelName
          in: query
          required: false
          schema:
            type: string
          description: Name of the hotel (loose match, case-insensitive)
        - name: latitude
          in: query
          required: false
          schema:
            type: number
            format: float
          description: Latitude coordinate for location-based search
        - name: longitude
          in: query
          required: false
          schema:
            type: number
            format: float
          description: Longitude coordinate for location-based search
        - name: radius
          in: query
          required: false
          schema:
            type: integer
            minimum: 1000
          description: Search radius in meters (minimum 1000m)
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 5000
            default: 200
          description: Maximum number of hotels to return
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Number of results to skip for pagination
        - name: minRating
          in: query
          required: false
          schema:
            type: number
            format: float
            minimum: 1
            maximum: 5
          description: Minimum guest rating (1.0-5.0)
        - name: minReviewsCount
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: Minimum number of reviews a hotel must have
        - name: starRating
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated list of star ratings (e.g., '3.5,4.0,5.0')
        - name: facilities
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated list of facility IDs
        - name: hotelTypeIds
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated list of hotel type IDs
        - name: chainIds
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated list of hotel chain IDs
        - name: strictFacilityFiltering
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: If true, only hotels with all specified facilities will be returned
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelList'
              example:
                data:
                  - id: RM42853
                    name: The Rove Grand Hotel
                    hotelDescription: >-
                      Located in the heart of downtown, The Rove Grand Hotel
                      offers luxury accommodations with stunning city views.
                      This 5-star property features a rooftop pool, full-service
                      spa, and three signature restaurants.
                    currency: USD
                    country: US
                    city: New York
                    latitude: 40.7128
                    longitude: -74.006
                    address: 123 Broadway
                    zip: '10007'
                    main_photo: https://static.rovemiles.com/hotels/RM42853_main.jpg
                    thumbnail: https://static.rovemiles.com/hotels/RM42853_thumb.jpg
                    hotelTypeId: 204
                    chainId: 14675
                    chain: Rove Hotels
                    stars: 5
                    facilityIds:
                      - 1
                      - 2
                      - 3
                      - 5
                      - 8
                      - 12
                      - 15
                      - 18
                    accessibilityAttributes:
                      attributes:
                        - entranceLeveled
                        - restaurantWheelchairAccessible
                        - poolAccessible
                      showerChair: available
                      entranceType: automatic
                      petFriendly: service animals only
                      entranceDoorWidth: 36
                      roomMaxGuestsNumber: 4
                      distanceFromTheElevatorToTheAccessibleRoom: 25
                  - id: RM36721
                    name: Rove Boutique Suites
                    hotelDescription: >-
                      Rove Boutique Suites offers stylish apartment-style
                      accommodations in a historic downtown building. Each suite
                      features a fully equipped kitchen, living area, and
                      premium bedding.
                    currency: USD
                    country: US
                    city: New York
                    latitude: 40.742
                    longitude: -73.989
                    address: 456 Park Avenue
                    zip: '10022'
                    main_photo: https://static.rovemiles.com/hotels/RM36721_main.jpg
                    thumbnail: https://static.rovemiles.com/hotels/RM36721_thumb.jpg
                    hotelTypeId: 201
                    chainId: 14675
                    chain: Rove Hotels
                    stars: 4
                    facilityIds:
                      - 1
                      - 2
                      - 7
                      - 9
                      - 12
                    accessibilityAttributes:
                      attributes:
                        - entranceLeveled
                        - cabinUnderSink
                      entranceType: manual
                      petFriendly: all pets welcome
                      entranceDoorWidth: 32
                      roomMaxGuestsNumber: 6
                      distanceFromTheElevatorToTheAccessibleRoom: 15
                  - id: RM51908
                    name: Rove Express Hotel
                    hotelDescription: >-
                      Perfect for business travelers, Rove Express Hotel offers
                      convenient accommodations with free high-speed WiFi,
                      24-hour business center, and complimentary breakfast.
                    currency: USD
                    country: US
                    city: New York
                    latitude: 40.7589
                    longitude: -73.9851
                    address: 789 5th Avenue
                    zip: '10019'
                    main_photo: https://static.rovemiles.com/hotels/RM51908_main.jpg
                    thumbnail: https://static.rovemiles.com/hotels/RM51908_thumb.jpg
                    hotelTypeId: 204
                    chainId: 14675
                    chain: Rove Hotels
                    stars: 3.5
                    facilityIds:
                      - 1
                      - 2
                      - 4
                      - 9
                    accessibilityAttributes:
                      attributes:
                        - entranceLeveled
                        - restaurantWheelchairAccessible
                      entranceType: automatic
                      petFriendly: service animals only
                      entranceDoorWidth: 34
                      roomMaxGuestsNumber: 4
                      distanceFromTheElevatorToTheAccessibleRoom: 20
                hotelIds:
                  - RM42853
                  - RM36721
                  - RM51908
                total: 129
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    HotelList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Hotel'
        hotelIds:
          type: array
          items:
            type: string
          description: List of all hotel IDs returned in the response
        total:
          type: integer
          description: Total number of hotels matching the search criteria
    Hotel:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the hotel
        name:
          type: string
          description: Name of the hotel
        hotelDescription:
          type: string
          description: >-
            Detailed description of the hotel, including location, amenities,
            and nearby attractions
        currency:
          type: string
          description: Default currency for hotel pricing
        country:
          type: string
          description: Country code in ISO-2 format
        city:
          type: string
          description: City name
        latitude:
          type: number
          format: float
          description: Latitude coordinate of the hotel
        longitude:
          type: number
          format: float
          description: Longitude coordinate of the hotel
        address:
          type: string
          description: Street address of the hotel
        zip:
          type: string
          description: Postal/ZIP code of the hotel
        main_photo:
          type: string
          format: uri
          description: URL to the main hotel photo
        thumbnail:
          type: string
          format: uri
          description: URL to the hotel thumbnail image
        hotelTypeId:
          type: integer
          description: >-
            ID representing the type of accommodation (e.g., hotel, apartment,
            resort)
        chainId:
          type: integer
          description: ID of the hotel chain, if applicable
        chain:
          type: string
          description: Name of the hotel chain, if applicable
        stars:
          type: number
          format: float
          description: Star rating of the hotel (1-5, with half-star increments)
        facilityIds:
          type: array
          items:
            type: integer
          description: IDs of facilities available at the hotel
        accessibilityAttributes:
          type: object
          properties:
            attributes:
              type: array
              items:
                type: string
              description: List of accessibility features available
            showerChair:
              type: string
            entranceType:
              type: string
              description: Type of entrance (e.g., electric, manual)
            petFriendly:
              type: string
            rampAngle:
              type: number
            rampLength:
              type: number
            entranceDoorWidth:
              type: number
            roomMaxGuestsNumber:
              type: number
            distanceFromTheElevatorToTheAccessibleRoom:
              type: number
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 400
            message: Bad Request
    Unauthorized:
      description: Unauthorized - Invalid or missing token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 401
            message: Unauthorized - Invalid or missing token
    InternalError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 500
            message: Internal Server Error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        API key for authentication. Add your API key to the Authorization header
        with this format: 'Bearer your_api_key_here'

````