openapi: 3.0.0
info:
  title: Booking Reviews API
  description: |
    Get the guest reviews of a Booking.com property, 10 per page.

    Each review carries its score, title, what the guest liked and disliked, language, date, traveler type, the guest's name and country, the room and stay dates, photos and the property's reply. The response also returns the property's overall rating and category scores, and the filters available for the property with their counts. Narrow the reviews by language, traveler type, score band, time of year, topic or text, and sort them.

    **Cross-linking**: pass `properties[].link` from the Booking API as `url`. The Booking Property API returns the same property's details and rooms.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Booking Reviews Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: 'Search engine. Must be set to: `booking_reviews`'
          schema:
            type: string
            enum: ["booking_reviews"]
        - name: url
          in: query
          required: true
          description: Booking.com property page URL, such as `https://www.booking.com/hotel/hr/city-dubrovnik.html`.
          schema:
            type: string
            maxLength: 2048
        - name: page
          in: query
          required: false
          description: Page of reviews, 10 per page.
          schema:
            type: integer
            minimum: 1
            maximum: 10000
            default: 1
        - name: sort_by
          in: query
          required: false
          description: Order of the reviews.
          schema:
            type: string
            enum: ["most_relevant", "newest", "oldest", "highest_score", "lowest_score"]
            default: "most_relevant"
        - name: languages
          in: query
          required: false
          description: Comma-separated language codes of the reviews to return, such as `en` or `en,de`, up to 20 codes.
          schema:
            type: string
            pattern: '^[a-z]{2,3}(-[a-z]{2,4})?(,[a-z]{2,3}(-[a-z]{2,4})?){0,19}$'
        - name: traveler_type
          in: query
          required: false
          description: Only reviews from this kind of traveler. `business_travelers` selects business trips, so those reviews can show another `travel_type`.
          schema:
            type: string
            enum: ["families", "couples", "groups_of_friends", "solo_travelers", "business_travelers"]
        - name: score
          in: query
          required: false
          description: 'Only reviews in this score band: `wonderful` 9+, `good` 7-9, `decent` 5-7, `poor` 3-5, `very_poor` 1-3.'
          schema:
            type: string
            enum: ["wonderful", "good", "decent", "poor", "very_poor"]
        - name: time_of_year
          in: query
          required: false
          description: Only reviews written in these months.
          schema:
            type: string
            enum: ["mar_may", "jun_aug", "sep_nov", "dec_feb"]
        - name: topic_id
          in: query
          required: false
          description: Only reviews that mention this topic, as listed in `filters.topics`.
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
        - name: q
          in: query
          required: false
          description: Only reviews containing this text.
          schema:
            type: string
            maxLength: 200
        - name: language
          in: query
          required: false
          description: Booking locale for category, filter and traveler names.
          schema:
            type: string
            enum: ["en-gb", "en-us", "de", "nl", "fr", "es", "es-ar", "ca", "it", "pt-pt", "pt-br", "no", "fi", "sv", "da", "cs", "hu", "ro", "ja", "zh-cn", "zh-tw", "pl", "el", "ru", "tr", "bg", "ar", "ko", "he", "lv", "uk", "id", "ms", "th", "et", "hr", "sk", "sr", "sl", "vi", "tl", "is", "lt", "en"]
            default: "en-us"
      responses:
        '200':
          description: Successful response
          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:
          type: object
          properties:
            total_results:
              type: integer
              description: Number of reviews matching the filters.
        place_result:
          type: object
          required: [name]
          properties:
            name:
              type: string
              description: Property name.
            link:
              type: string
              description: Property page on Booking.com.
            address:
              type: string
              description: Street address.
            city:
              type: string
              description: City.
            country_code:
              type: string
              description: Country code of the property.
            rating:
              type: number
              description: Overall review score out of 10.
            reviews_count:
              type: integer
              description: Total number of reviews.
            category_scores:
              type: array
              description: Scores by category, such as location, cleanliness and staff.
              items:
                type: object
                required: [key, score]
                properties:
                  key:
                    type: string
                    description: Category identifier.
                  name:
                    type: string
                    description: Category name in the requested language.
                  score:
                    type: number
                    description: Category score out of 10.
                  reviews_count:
                    type: integer
                    description: Number of reviews that scored this category.
                  area_low:
                    type: number
                    description: Lower end of the typical score in the area.
                  area_high:
                    type: number
                    description: Upper end of the typical score in the area.
        reviews:
          type: array
          items:
            $ref: '#/components/schemas/Review'
        filters:
          type: object
          description: Filters available for this property, with the number of reviews each matches.
          properties:
            languages:
              type: array
              items:
                $ref: '#/components/schemas/FilterOption'
            traveler_types:
              type: array
              items:
                $ref: '#/components/schemas/FilterOption'
            scores:
              type: array
              items:
                $ref: '#/components/schemas/FilterOption'
            times_of_year:
              type: array
              items:
                $ref: '#/components/schemas/FilterOption'
            topics:
              type: array
              items:
                type: object
                required: [topic_id, name]
                properties:
                  topic_id:
                    type: integer
                    description: Value to pass as `topic_id`.
                  name:
                    type: string
                    description: Topic name.
        pagination:
          type: object
          properties:
            current:
              type: integer
              description: Current page.
            next_page:
              type: integer
              description: Value to pass as `page` for the next page.
            total_pages:
              type: integer
              description: Number of pages of matching reviews.
        error:
          type: string
          description: Why there are no reviews to return.
    Review:
      type: object
      required: [position, review_id, rating, date, author, stay]
      properties:
        position:
          type: integer
          description: Position of the review across pages.
        review_id:
          type: string
          description: Booking identifier of the review.
        title:
          type: string
          description: Review title.
        liked:
          type: string
          description: What the guest liked.
        disliked:
          type: string
          description: What the guest disliked.
        rating:
          type: number
          description: Review score out of 10.
        language:
          type: string
          description: Language the review was written in, such as `en` or `en-us`.
        date:
          type: string
          format: date-time
          description: Date the review was written.
        helpful_votes:
          type: integer
          description: Number of guests who found the review helpful.
        travel_type:
          type: string
          description: Kind of traveler, as Booking names it in the requested `language`.
        author:
          type: object
          required: [is_anonymous]
          properties:
            name:
              type: string
              description: Guest name as shown on Booking.com.
            country:
              type: string
              description: Guest country.
            country_code:
              type: string
              description: Guest country code.
            avatar:
              type: string
              description: Guest avatar URL.
            is_anonymous:
              type: boolean
              description: Whether the guest reviewed anonymously.
        stay:
          type: object
          properties:
            room_type:
              type: string
              description: Room the guest stayed in.
            nights:
              type: integer
              description: Number of nights.
            check_in_date:
              type: string
              format: date
              description: Check-in date.
            check_out_date:
              type: string
              format: date
              description: Check-out date.
        reply:
          type: string
          description: The property's reply to the review.
        photos:
          type: array
          description: Photo URLs the guest attached.
          items:
            type: string
    FilterOption:
      type: object
      required: [value, name]
      properties:
        value:
          type: string
          description: Value to pass as the matching parameter.
        name:
          type: string
          description: Name in the requested language.
        count:
          type: integer
          description: Number of reviews this option matches.
    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: Booking.com 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
      properties:
        engine:
          type: string
        url:
          type: string
        page:
          type: integer
        sort_by:
          type: string
        languages:
          type: string
        traveler_type:
          type: string
        score:
          type: string
        time_of_year:
          type: string
        topic_id:
          type: integer
        q:
          type: string
        language:
          type: string
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong