openapi: 3.0.0
info:
  title: Airbnb Property Reviews API
  description: |
    Retrieve guest reviews for a specific Airbnb property, including the review text, rating, reviewer details, host responses, translations, and review topic facets.

    **Cross-linking**: The `property_id` parameter required by this API is obtained from the Airbnb Search API or Airbnb Property API. Use it together with `q`, `sort_by`, and `page` to navigate the full reviews list.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Airbnb Property Reviews
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Set to `airbnb_property_reviews` for this API.
          schema:
            type: string
            enum: ["airbnb_property_reviews"]
            default: "airbnb_property_reviews"
        - name: property_id
          in: query
          required: true
          description: Airbnb property ID. Obtained from Airbnb Search or Property API results, or from Airbnb URLs (`https://www.airbnb.com/rooms/{property_id}`).
          schema:
            type: string
        - name: q
          in: query
          required: false
          description: Filter reviews by a search query (e.g., a keyword that should appear in the review text).
          schema:
            type: string
        - name: sort_by
          in: query
          required: false
          description: Sort order for the returned reviews.
          schema:
            type: string
            enum: ["most_relevant", "most_recent", "highest_rating", "lowest_rating"]
            default: "most_relevant"
        - name: page
          in: query
          required: false
          description: Page number for paginating through reviews. Each page returns up to 10 reviews.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: airbnb_domain
          in: query
          required: false
          description: Airbnb domain to use. Affects language and regional results.
          schema:
            type: string
            enum: ["airbnb.com", "sw.airbnb.com", "sq.airbnb.com", "ar.airbnb.com", "airbnb.com.ar", "airbnb.am", "airbnb.com.au", "airbnb.at", "airbnb.az", "airbnb.be", "fr.airbnb.be", "airbnb.com.bz", "airbnb.com.bo", "airbnb.ba", "airbnb.com.br", "bg.airbnb.com", "airbnb.ca", "fr.airbnb.ca", "airbnb.cl", "airbnb.cn", "airbnb.com.co", "airbnb.co.cr", "hr.airbnb.com", "airbnb.cz", "airbnb.dk", "airbnb.com.ec", "airbnb.com.sv", "airbnb.com.ee", "airbnb.fi", "airbnb.fr", "ka.airbnb.com", "airbnb.de", "airbnb.gr", "airbnb.com.gt", "airbnb.gy", "airbnb.com.hn", "airbnb.com.hk", "airbnb.hu", "airbnb.is", "airbnb.co.in", "hi.airbnb.co.in", "kn.airbnb.co.in", "mr.airbnb.co.in", "airbnb.co.id", "airbnb.ie", "ga.airbnb.ie", "he.airbnb.com", "airbnb.it", "airbnb.jp", "airbnb.lv", "airbnb.lt", "airbnb.lu", "de.airbnb.lu", "airbnb.com.my", "mt.airbnb.com.mt", "airbnb.mx", "airbnb.me", "airbnb.nl", "airbnb.co.nz", "airbnb.com.ni", "mk.airbnb.com", "airbnb.no", "airbnb.com.pa", "airbnb.com.py", "airbnb.com.pe", "airbnb.com.ph", "airbnb.pl", "airbnb.pt", "airbnb.com.ro", "airbnb.ru", "airbnb.rs", "airbnb.com.sg", "sk.airbnb.com", "airbnb.si", "xh.airbnb.co.za", "zu.airbnb.co.za", "airbnb.co.kr", "airbnb.cat", "airbnb.es", "airbnb.se", "fr.airbnb.ch", "airbnb.ch", "it.airbnb.ch", "airbnb.com.tw", "th.airbnb.com", "airbnb.com.tr", "airbnb.com.ua", "airbnb.ae", "airbnb.co.uk", "zh.airbnb.com", "zh-t.airbnb.com", "es.airbnb.com", "airbnb.co.ve", "airbnb.com.vn"]
            default: "airbnb.com"
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReviewsResponse'
        '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:
    ReviewsResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        search_information:
          $ref: '#/components/schemas/SearchInformation'
        reviews:
          type: array
          description: Reviews returned for the requested page
          items:
            $ref: '#/components/schemas/Review'
        topics:
          type: array
          description: Review topics surfaced by Airbnb for this property (e.g., cleanliness, location)
          items:
            $ref: '#/components/schemas/Topic'
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Error message returned when no reviews can be retrieved.

    SearchMetadata:
      type: object
      required: [id, 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: Airbnb 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
          description: The engine used for this search
        airbnb_domain:
          type: string
          description: The Airbnb domain used for this search
        property_id:
          type: string
          description: The property ID used for this search
        q:
          type: string
          description: The search query used to filter reviews
        sort_by:
          type: string
          description: The sort order used for this search
        page:
          type: integer
          description: The page number used for this search

    SearchInformation:
      type: object
      properties:
        reviews:
          type: integer
          description: Total number of reviews available for the property

    Review:
      type: object
      properties:
        review_id:
          type: string
          description: Unique review identifier
        text:
          type: string
          description: Review text in the original language with newlines preserved
        highlighted_snippets:
          type: array
          description: Snippets within the review text that Airbnb highlighted (matched against the `q` query)
          items:
            type: string
        language:
          type: string
          description: ISO language code of the review (e.g., `en`, `es`)
        has_translation:
          type: boolean
          description: Present and `true` when Airbnb provides a translation of the review
        translated_text:
          type: string
          description: Translated review text with newlines preserved
        translated_highlighted_snippets:
          type: array
          description: Highlighted snippets within the translated review text
          items:
            type: string
        user:
          $ref: '#/components/schemas/Reviewer'
        rating:
          type: integer
          description: Numeric review rating (1-5)
        date:
          type: string
          description: Localized review date as displayed by Airbnb
        iso_date:
          type: string
          description: Review creation timestamp in ISO 8601 format
        details:
          type: string
          description: Additional review highlight string surfaced by Airbnb
        response:
          $ref: '#/components/schemas/HostResponse'

    Reviewer:
      type: object
      properties:
        id:
          type: string
          description: Unique reviewer identifier
        name:
          type: string
          description: Reviewer display name
        profile_link:
          type: string
          description: URL to the reviewer's Airbnb profile page
        is_superhost:
          type: boolean
          description: Whether the reviewer is a Superhost
        details:
          type: string
          description: Reviewer location, if available
        avatar:
          type: string
          description: URL of the reviewer's profile picture

    HostResponse:
      type: object
      properties:
        text:
          type: string
          description: Host response text in the original language with newlines preserved
        has_translation:
          type: boolean
          description: Present and `true` when Airbnb provides a translation of the host response
        translated_text:
          type: string
          description: Translated host response text with newlines preserved
        user:
          $ref: '#/components/schemas/Reviewer'
        date:
          type: string
          description: Localized response date as displayed by Airbnb

    Topic:
      type: object
      properties:
        topic_id:
          type: string
          description: Topic identifier (lowercased)
        name:
          type: string
          description: Localized topic display name
        count:
          type: integer
          description: Number of reviews tagged with this topic

    Pagination:
      type: object
      properties:
        current:
          type: integer
          description: Current page number
        next:
          type: integer
          description: Next page number, when more reviews are available
        previous:
          type: integer
          description: Previous page number, when not on the first page

    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong