openapi: 3.0.0
info:
  title: Yelp Search API
  description: |
    Search Yelp for local businesses by term and location, returning organic
    business listings, ads, the search's category breadcrumbs, and related searches.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Yelp Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Set to `yelp_search` to use this API.
          schema:
            type: string
            enum: ["yelp_search"]
        - name: location
          in: query
          required: true
          description: 'Geographic location to search around. Accepts a city and state, an address, or a ZIP code, e.g. "San Francisco, CA".'
          schema:
            type: string
        - name: q
          in: query
          required: false
          description: Search term, such as a business name or category keyword.
          schema:
            type: string
            maxLength: 128
        - name: sort_by
          in: query
          required: false
          description: Ordering of the results. `review_count` requires `device=desktop`.
          schema:
            type: string
            enum: ["recommended", "rating", "review_count"]
            default: "recommended"
        - name: price
          in: query
          required: false
          description: 'Filter by price level, from 1 ($) to 4 ($$$$). Comma-separate multiple levels, e.g. "1,2".'
          schema:
            type: string
            pattern: '^[1-4](,[1-4])*$'
        - name: category
          in: query
          required: false
          description: 'Filter by a Yelp category alias, e.g. "restaurants" or "barbers".'
          schema:
            type: string
            pattern: '^[a-z0-9_-]{1,64}$'
        - name: filters
          in: query
          required: false
          description: 'Filter by Yelp attribute tokens, comma-separated, e.g. "GoodForKids,RestaurantsDelivery". Yelp ignores tokens it does not recognize.'
          schema:
            type: string
            pattern: '^[A-Za-z0-9_.]+(,[A-Za-z0-9_.]+)*$'
        - name: page
          in: query
          required: false
          description: >-
            Page of results. A mobile page holds up to 80 results (Yelp uses 60 or 10 for some searches),
            a desktop page 10. Yelp lists at most 240 results in total for a search term and location,
            across all pages combined. Yelp can reorder results between requests, so a business may
            appear on more than one page. Use `place_id` to deduplicate results.
          schema:
            type: integer
            minimum: 1
            maximum: 24
            default: 1
        - name: device
          in: query
          required: false
          description: >-
            Device to search on. `mobile` (the default) returns up to 80 organic results per page.
            `desktop` returns 10 per page and adds `neighborhoods` and `is_service_area_business`
            to results. Desktop results come without `distance`, and desktop organic results without
            `phone`. Desktop addresses give the street and city only, and desktop
            `search_information.location` has no `gps_coordinates`. Desktop categories carry no `alias`,
            and their titles can differ from mobile's. Desktop ads come without `tracking_link`.
          schema:
            type: string
            enum: ["mobile", "desktop"]
            default: "mobile"
      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:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        search_information:
          $ref: '#/components/schemas/SearchInformation'
        ads:
          type: array
          description: Sponsored business listings.
          items:
            $ref: '#/components/schemas/AdResult'
        local_results:
          type: array
          description: Organic business listings.
          items:
            $ref: '#/components/schemas/OrganicResult'
        related_searches:
          type: array
          description: Suggested related searches.
          items:
            $ref: '#/components/schemas/RelatedSearch'
        breadcrumbs:
          type: array
          description: Yelp's category trail for the search, such as Yelp > Restaurants > Pizza on mobile or Restaurants > Pizza on desktop.
          items:
            $ref: '#/components/schemas/Breadcrumb'
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Error message when Yelp returns no results for the search.
    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: "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"
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: Search engine used
        q:
          type: string
          description: The search term
        location:
          type: string
          description: The location provided in the request
        sort_by:
          type: string
          description: The ordering applied to the results
        price:
          type: string
          description: The price levels filtered on
        category:
          type: string
          description: The Yelp category alias filtered on
        filters:
          type: string
          description: The Yelp attribute tokens filtered on
        page:
          type: integer
          description: The page of results requested
        device:
          type: string
          description: The device the search was run for
    SearchInformation:
      type: object
      properties:
        query_displayed:
          type: string
          description: The search term as interpreted by Yelp
        location_displayed:
          type: string
          description: The location as interpreted by Yelp
        total_results:
          type: integer
          description: Total number of results available
        location:
          type: object
          description: The resolved location of the search
          properties:
            city:
              type: string
            state:
              type: string
            country_code:
              type: string
            gps_coordinates:
              type: object
              properties:
                latitude:
                  type: number
                longitude:
                  type: number
    LocalResult:
      type: object
      required: [position, place_id, alias, title, link, reviews]
      properties:
        position:
          type: integer
          description: Rank of the result across the search's pages. Ads are numbered from 1 on each page.
        place_id:
          type: string
          description: Yelp's encrypted business identifier
        alias:
          type: string
          description: Yelp business alias (slug)
        title:
          type: string
          description: Business name
        link:
          type: string
          description: URL to the Yelp business page
        rating:
          type: number
          description: Average star rating
        reviews:
          type: integer
          description: Number of reviews
        price:
          type: string
          description: Price level indicator (for example, $$)
        categories:
          type: array
          items:
            $ref: '#/components/schemas/Category'
        address:
          type: string
          description: Formatted business address
        phone:
          type: string
          description: Formatted phone number
        distance:
          type: string
          description: Distance from the search center, formatted (for example, "4.3 mi")
        extracted_distance:
          type: number
          description: Distance from the search center in miles
        review_snippet:
          type: string
          description: Excerpt from a review
        review_snippet_highlighted_words:
          type: array
          items:
            type: string
          description: Words highlighted within the review snippet
        description:
          type: string
          description: Text the business wrote about itself, which Yelp shows in place of a review excerpt.
        highlights:
          type: array
          items:
            type: string
          description: Business highlight labels
        thumbnail:
          type: string
          description: Primary business photo URL
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        is_verified_license:
          type: boolean
          description: Whether the business has a Yelp-verified license
        neighborhoods:
          type: array
          items:
            type: string
          description: Neighborhoods the business is listed in.
        is_service_area_business:
          type: boolean
          description: Whether the business travels to the customer instead of serving one address.
    AdResult:
      allOf:
        - $ref: '#/components/schemas/LocalResult'
        - type: object
          properties:
            tracking_link:
              type: string
              description: Yelp redirect URL for the listing
    OrganicResult:
      allOf:
        - $ref: '#/components/schemas/LocalResult'
        - type: object
          required: [address]
    Category:
      type: object
      required: [title]
      properties:
        title:
          type: string
          description: Category display name
        alias:
          type: string
          description: Category alias usable as the `category` parameter
    Image:
      type: object
      required: [original]
      properties:
        title:
          type: string
          description: Photo caption
        original:
          type: string
          description: Full-size photo URL
        thumbnail:
          type: string
          description: Thumbnail photo URL
    RelatedSearch:
      type: object
      required: [query, link]
      properties:
        query:
          type: string
          description: Suggested search term
        link:
          type: string
          description: URL for the suggested search
    Breadcrumb:
      type: object
      required: [title]
      properties:
        title:
          type: string
          description: Category name, or `Yelp` for the crumb that links to Yelp's home page
        link:
          type: string
          description: URL of the Yelp search for the category in the same location, or of Yelp's home page for the `Yelp` crumb
    Pagination:
      type: object
      required: [current]
      properties:
        current:
          type: integer
          description: Current page number
        next:
          type: string
          description: Yelp URL for the next page of results
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong