---
openapi: 3.0.0
info:
  title: Yelp Place API
  description: Retrieve Yelp business details, photos, amenities, opening hours, and
    optional named menus, regional domains, special hours, licenses, and consumer alerts.
  version: 1.0.0
servers:
- url: https://www.searchapi.io/api/v1
paths:
  "/search":
    get:
      summary: Yelp Place
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      parameters:
      - name: engine
        in: query
        required: true
        description: Set to `yelp_place`.
        schema:
          type: string
          enum:
          - yelp_place
      - name: place_id
        in: query
        required: true
        description: Yelp business ID or alias. Accepts Unicode letters, combining marks, numbers, underscores, and hyphens. Take place_id or alias from yelp_search.local_results.
        schema:
          type: string
          minLength: 1
          maxLength: 200
      - name: full_menu
        in: query
        required: false
        description: Set to true to include full_menu_results alongside place_result.
          When no Yelp menu exists, place_result is returned and search_information.has_menu
          is false.
        schema:
          type: boolean
      - name: yelp_domain
        in: query
        required: false
        description: Yelp domain to request. Defaults to yelp.com. The www prefix
          is optional for www domains.
        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: menu_name
        in: query
        required: false
        description: Exact name from full_menu_results.available_menus. Requires full_menu=true.
          Omit to retrieve the default menu and available choices. An unknown menu
          returns HTTP 400 when the business has a Yelp menu.
        schema:
          type: string
          maxLength: 200
      - name: business_alert
        in: query
        required: false
        description: Set to true to include Yelp consumer alert types and available
          alert history, descriptions, and dates. Historical alerts are returned separately
          from the current alert. Alert text is usually in English, including on
          non-English Yelp domains. Defaults to false.
        schema:
          type: boolean
          default: false
      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
      properties:
        search_metadata:
          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: Yelp URL for this search
            html_url:
              type: string
              description: URL to view HTML results
            json_url:
              type: string
              description: URL to view JSON results
        search_parameters:
          type: object
          properties:
            engine:
              type: string
              enum:
              - yelp_place
            place_id:
              type: string
              minLength: 1
              maxLength: 200
            full_menu:
              type: boolean
            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
            menu_name:
              type: string
              maxLength: 200
            business_alert:
              type: boolean
              default: false
        place_result:
          type: object
          required:
          - place_id
          - title
          - link
          - images_link
          properties:
            place_id:
              type: string
            alias:
              type: string
            title:
              type: string
            link:
              type: string
            description:
              type: string
            rating:
              type: number
            reviews:
              type: integer
            price:
              type: string
            categories:
              type: array
              items:
                type: object
                required:
                - title
                properties:
                  title:
                    type: string
                  alias:
                    type: string
            address:
              type: string
            neighborhoods:
              type: array
              items:
                type: string
            country_code:
              type: string
            timezone:
              type: string
            phone:
              type: string
            website:
              type: string
            website_menu_link:
              type: string
            menu_link:
              type: string
            directions_link:
              type: string
            images_link:
              type: string
            is_claimed:
              type: boolean
              description: Whether the business owner has claimed the Yelp page.
            is_open:
              type: boolean
              description: Whether the business is currently open.
            history:
              type: object
              properties:
                description:
                  type: string
                year_established:
                  type: string
            open_hours:
              type: array
              items:
                type: object
                properties:
                  day:
                    type: string
                  hours:
                    type: string
                  regular_hours:
                    type: string
                  is_special:
                    type: boolean
                    description: Whether the day has special opening hours.
            amenities:
              type: array
              items:
                type: object
                required:
                - is_available
                properties:
                  title:
                    type: string
                  alias:
                    type: string
                  is_available:
                    type: boolean
                    description: Whether the amenity is available.
            images:
              type: array
              items:
                type: object
                required:
                - original
                - thumbnail
                properties:
                  title:
                    type: string
                  original:
                    type: string
                  thumbnail:
                    type: string
            ambiance:
              type: object
              properties:
                highlights:
                  type: array
                  items:
                    type: string
                categories:
                  type: array
                  items:
                    type: object
                    properties:
                      title:
                        type: string
                      photos:
                        type: integer
                      images:
                        type: array
                        items:
                          type: object
                          required:
                          - original
                          - thumbnail
                          properties:
                            title:
                              type: string
                            original:
                              type: string
                            thumbnail:
                              type: string
            popular_items:
              type: array
              items:
                type: object
                properties:
                  title:
                    type: string
                  price:
                    type: string
                  extracted_price:
                    type: number
                  reviews:
                    type: integer
                  photos:
                    type: integer
                  rating:
                    type: number
                  thumbnail:
                    type: string
            review_highlights:
              type: array
              items:
                type: object
                required:
                - link
                properties:
                  review_id:
                    type: string
                  link:
                    type: string
                  text:
                    type: string
                  highlight:
                    type: string
                  reviews:
                    type: integer
                  user:
                    type: object
                    properties:
                      name:
                        type: string
                      user_id:
                        type: string
                  thumbnail:
                    type: string
            community_questions:
              type: array
              items:
                type: object
                properties:
                  question_id:
                    type: string
                  question:
                    type: string
                  answer:
                    type: string
                  iso_date:
                    type: string
                  helpful_votes:
                    type: integer
                  user:
                    type: object
                    properties:
                      name:
                        type: string
                      user_id:
                        type: string
            health_inspections:
              type: array
              items:
                type: object
                properties:
                  score:
                    type: string
                  iso_date:
                    type: string
                  violations:
                    type: array
                    items:
                      type: string
                  provider:
                    type: object
                    properties:
                      name:
                        type: string
                      link:
                        type: string
            is_claimable:
              type: boolean
              description: Whether the business owner can claim the Yelp page.
            is_permanently_closed:
              type: boolean
              description: Whether the business has closed for good.
            gps_coordinates:
              type: object
              properties:
                latitude:
                  type: number
                longitude:
                  type: number
            business_alerts:
              type: array
              items:
                type: object
                required:
                - type
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  description:
                    type: string
                  start_date:
                    type: string
                  end_date:
                    type: string
            business_alerts_history:
              type: array
              items:
                type: object
                required:
                - type
                - start_date
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  description:
                    type: string
                  start_date:
                    type: string
                  end_date:
                    type: string
            business_owner:
              type: object
              properties:
                name:
                  type: string
                role:
                  type: string
                description:
                  type: string
                thumbnail:
                  type: string
            hours_last_updated:
              type: string
            special_hours:
              type: array
              items:
                type: object
                properties:
                  date:
                    type: string
                  day:
                    type: string
                  hours:
                    type: string
                  holiday_name:
                    type: string
                  has_verified_hours:
                    type: boolean
                    description: Whether the special hours have been verified.
            service_areas:
              type: array
              items:
                type: string
            verified_licenses:
              type: array
              items:
                type: object
                properties:
                  issuing_authority:
                    type: string
                  license_number:
                    type: string
                  licensee:
                    type: string
                  verification_date:
                    type: string
                  trade:
                    type: string
            closed_until:
              type: string
          description: Business details for the requested place.
        full_menu_results:
          type: object
          properties:
            title:
              type: string
            link:
              type: string
            sections:
              type: array
              items:
                type: object
                properties:
                  title:
                    type: string
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        title:
                          type: string
                        link:
                          type: string
                        description:
                          type: string
                        reviews:
                          type: integer
                        prices:
                          type: array
                          items:
                            type: object
                            properties:
                              price:
                                type: string
                              extracted_price:
                                type: number
                        photos:
                          type: integer
                        thumbnail:
                          type: string
            menu_name:
              type: string
            available_menus:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  link:
                    type: string
        search_information:
          type: object
          required:
          - has_menu
          properties:
            has_menu:
              type: boolean
        error:
          type: string
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string