---
openapi: 3.0.0
info:
  title: Yelp Reviews API
  description: Retrieve Yelp reviews, ratings, reviewer profiles, photos, reactions,
    business replies, and pagination. Supports recommended and non-recommended reviews.
  version: 1.0.0
servers:
- url: https://www.searchapi.io/api/v1
paths:
  "/search":
    get:
      summary: Yelp Reviews
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      parameters:
      - name: engine
        in: query
        required: true
        description: Set to yelp_reviews.
        schema:
          type: string
          enum:
          - yelp_reviews
      - name: place_id
        in: query
        required: true
        description: Encoded Yelp business ID from yelp_search.local_results.place_id.
          Aliases are not supported.
        schema:
          type: string
          pattern: "^[A-Za-z0-9_-]{22}$"
      - name: yelp_domain
        in: query
        required: false
        description: Yelp domain to request. Defaults to yelp.com. The www prefix
          is optional for www domains. Returned Yelp links use this domain.
        schema:
          type: string
          enum:
          - www.yelp.com
          - www.yelp.ca
          - fr.yelp.ca
          - www.yelp.co.uk
          - www.yelp.ie
          - www.yelp.com.au
          - www.yelp.co.nz
          - www.yelp.de
          - www.yelp.at
          - de.yelp.ch
          - en.yelp.ch
          - fr.yelp.ch
          - it.yelp.ch
          - www.yelp.fr
          - en.yelp.be
          - fr.yelp.be
          - nl.yelp.be
          - www.yelp.es
          - www.yelp.com.ar
          - www.yelp.cl
          - www.yelp.com.mx
          - www.yelp.it
          - www.yelp.nl
          - www.yelp.dk
          - www.yelp.no
          - www.yelp.se
          - fi.yelp.fi
          - sv.yelp.fi
          - www.yelp.pl
          - www.yelp.cz
          - www.yelp.pt
          - www.yelp.com.br
          - www.yelp.com.tr
          - www.yelp.co.jp
          - en.yelp.com.hk
          - zh.yelp.com.hk
          - www.yelp.com.tw
          - www.yelp.com.sg
          - en.yelp.my
          - ms.yelp.my
          - en.yelp.com.ph
          - fil.yelp.com.ph
          - yelp.com
          - yelp.ca
          - yelp.co.uk
          - yelp.ie
          - yelp.com.au
          - yelp.co.nz
          - yelp.de
          - yelp.at
          - yelp.fr
          - yelp.es
          - yelp.com.ar
          - yelp.cl
          - yelp.com.mx
          - yelp.it
          - yelp.nl
          - yelp.dk
          - yelp.no
          - yelp.se
          - yelp.pl
          - yelp.cz
          - yelp.pt
          - yelp.com.br
          - yelp.com.tr
          - yelp.co.jp
          - yelp.com.tw
          - yelp.com.sg
          default: yelp.com
      - name: sort_by
        in: query
        required: false
        description: 'Review ordering: most_relevant, newest, oldest, highest_rating,
          lowest_rating, elites. Defaults to most_relevant. Cannot be combined with
          q or not_recommended=true.'
        schema:
          type: string
          enum:
          - most_relevant
          - newest
          - oldest
          - highest_rating
          - lowest_rating
          - elites
          default: most_relevant
      - name: hl
        in: query
        required: false
        description: Filter recommended reviews by two- or three-letter language code.
          Defaults to the selected domain's language (en on yelp.com). Available languages
          and counts are returned in review_languages. Cannot be used with not_recommended=true.
        schema:
          type: string
          pattern: "^[a-z]{2,3}$"
      - name: q
        in: query
        required: false
        description: Search within reviews using Yelp search relevance. Matches need
          not contain the exact phrase, and ordering can vary between pages. Cannot
          be combined with sort_by, rating, or not_recommended=true.
        schema:
          type: string
          maxLength: 2000
      - name: rating
        in: query
        required: false
        description: Filter by ratings from 1 to 5, separated by commas, e.g. 4,5.
          All ratings are included by default. Cannot be combined with q or not_recommended=true.
        schema:
          type: string
          pattern: "^[1-5](,[1-5]){0,4}$"
      - name: num
        in: query
        required: false
        description: Results per page, from 1 to 49; defaults to 49. Non-recommended
          reviews have fixed 10-result pages; omit this parameter or use 10 in that
          mode.
        schema:
          type: integer
          minimum: 1
          maximum: 49
      - name: not_recommended
        in: query
        required: false
        description: Set to true to retrieve reviews Yelp does not recommend. These
          pages contain up to 10 reviews and do not support q, sort_by, rating, or
          hl. Defaults to false.
        schema:
          type: boolean
          default: false
      - name: next_page_token
        in: query
        required: false
        description: Use pagination.next_page_token from the preceding response and
          keep the other parameters unchanged. Applies to both recommended and non-recommended
          reviews. Omit for the first page.
        schema:
          type: string
          maxLength: 1024
      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, place_result, search_information]
      properties:
        place_result:
          type: object
          required: [place_id, title, link]
          properties:
            place_id:
              type: string
            alias:
              type: string
            title:
              type: string
            link:
              type: string
            rating:
              type: number
            reviews:
              type: integer
        search_information:
          type: object
          required: [total_results]
          properties:
            total_results:
              type: integer
              description: Number of reviews that match the request, estimated by Yelp
                when q is used.
        review_languages:
          type: array
          items:
            type: object
            properties:
              hl:
                type: string
              count:
                type: integer
        reviews:
          type: array
          items:
            type: object
            required: [position, review_id, link, text, rating]
            properties:
              position:
                type: integer
              review_id:
                type: string
              link:
                type: string
              text:
                type: string
              text_highlighted_words:
                type: array
                items:
                  type: string
                description: Words Yelp highlights in text as matches for q.
              language:
                type: string
              rating:
                type: integer
              iso_date:
                type: string
              user:
                type: object
                properties:
                  user_id:
                    type: string
                  name:
                    type: string
                  link:
                    type: string
                  address:
                    type: string
                  reviews:
                    type: integer
                  friends:
                    type: integer
                  photos:
                    type: integer
                  thumbnail:
                    type: string
                  elite_year:
                    type: integer
              reactions:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                    title:
                      type: string
                    count:
                      type: integer
              response:
                type: object
                properties:
                  text:
                    type: string
                  iso_date:
                    type: string
                  user:
                    type: object
                    properties:
                      user_id:
                        type: string
                      name:
                        type: string
                      thumbnail:
                        type: string
                      role:
                        type: string
              images:
                type: array
                items:
                  type: object
                  properties:
                    original:
                      type: string
                    thumbnail:
                      type: string
                    title:
                      type: string
          description: iso_date retains the source timezone offset. elite_year is the
            two-digit year displayed by Yelp. Reactions retain Yelp types (helpful, thanks, love_this, oh_no).
        pagination:
          type: object
          required: [next_page_token]
          properties:
            next_page_token:
              type: string
        error:
          type: string
          description: Error message when Yelp returns no reviews for the search.
        search_metadata:
          type: object
          required: [id, status, created_at]
          properties:
            id:
              type: string
            status:
              type: string
            created_at:
              type: string
            request_time_taken:
              type: number
            parsing_time_taken:
              type: number
            total_time_taken:
              type: number
            request_url:
              type: string
            html_url:
              type: string
            json_url:
              type: string
        search_parameters:
          type: object
          required: [engine, place_id]
          properties:
            engine:
              type: string
              enum:
              - yelp_reviews
            place_id:
              type: string
              pattern: "^[A-Za-z0-9_-]{22}$"
            sort_by:
              type: string
              enum:
              - most_relevant
              - newest
              - oldest
              - highest_rating
              - lowest_rating
              - elites
              default: most_relevant
            hl:
              type: string
              pattern: "^[a-z]{2,3}$"
            q:
              type: string
              maxLength: 2000
            rating:
              type: string
              pattern: "^[1-5](,[1-5]){0,4}$"
            num:
              type: integer
              minimum: 1
              maximum: 49
            not_recommended:
              type: boolean
              default: false
            next_page_token:
              type: string
              maxLength: 1024
            yelp_domain:
              type: string
              enum:
              - www.yelp.com
              - www.yelp.ca
              - fr.yelp.ca
              - www.yelp.co.uk
              - www.yelp.ie
              - www.yelp.com.au
              - www.yelp.co.nz
              - www.yelp.de
              - www.yelp.at
              - de.yelp.ch
              - en.yelp.ch
              - fr.yelp.ch
              - it.yelp.ch
              - www.yelp.fr
              - en.yelp.be
              - fr.yelp.be
              - nl.yelp.be
              - www.yelp.es
              - www.yelp.com.ar
              - www.yelp.cl
              - www.yelp.com.mx
              - www.yelp.it
              - www.yelp.nl
              - www.yelp.dk
              - www.yelp.no
              - www.yelp.se
              - fi.yelp.fi
              - sv.yelp.fi
              - www.yelp.pl
              - www.yelp.cz
              - www.yelp.pt
              - www.yelp.com.br
              - www.yelp.com.tr
              - www.yelp.co.jp
              - en.yelp.com.hk
              - zh.yelp.com.hk
              - www.yelp.com.tw
              - www.yelp.com.sg
              - en.yelp.my
              - ms.yelp.my
              - en.yelp.com.ph
              - fil.yelp.com.ph
              - yelp.com
              - yelp.ca
              - yelp.co.uk
              - yelp.ie
              - yelp.com.au
              - yelp.co.nz
              - yelp.de
              - yelp.at
              - yelp.fr
              - yelp.es
              - yelp.com.ar
              - yelp.cl
              - yelp.com.mx
              - yelp.it
              - yelp.nl
              - yelp.dk
              - yelp.no
              - yelp.se
              - yelp.pl
              - yelp.cz
              - yelp.pt
              - yelp.com.br
              - yelp.com.tr
              - yelp.co.jp
              - yelp.com.tw
              - yelp.com.sg
              default: yelp.com
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string