Blog / API guides

Yelp Reviews API: Business Search and Reviews as JSON

7 Aug 2026Updated 26 Oct 2026Perceptlayer6 min read

You can get Yelp business search results, business details and reviews as JSON from three endpoints: /v1/yelp/search, /v1/yelp/business and /v1/yelp/reviews. Each successful call costs 1 credit, failed calls cost nothing, and one X-API-Key header authenticates all three. This guide shows the parameters, a real response for each of the two recorded endpoints and a cost example. It also covers when Yelp's own developer API is the better fit.

What does the Yelp API return?

The Yelp API returns JSON for three jobs: finding businesses, reading one business's details and reading its reviews. A typical flow is to search by name and location, take the business alias from the result, then pass that alias as business to the other two endpoints. Every response has a success flag, a data object and a meta object.

Each endpoint has its own page with a playground: Search, Business and Reviews. Yelp sits in the Reviews APIs area of the catalogue.

How do you search for Yelp businesses?

Call GET /v1/yelp/search with a query and a location. The response lists matching businesses with their position, rating, review count, price level, categories, address and photo, so one call is enough to find a business and get its alias for the next two calls.

curl "https://api.perceptlayer.com/v1/yelp/search?query=gary+danko&location=San+Francisco%2C+CA" \
  -H "X-API-Key: $API_KEY"

This is an excerpt of the recorded response for that request:

{
  "success": true,
  "data": {
    "query": "gary danko",
    "location": "San Francisco, CA",
    "page": 1,
    "results": [
      {
        "position": 1,
        "encid": "WavvLdfdP6g8aZTtbBQHTw",
        "alias": "gary-danko-san-francisco",
        "name": "Gary Danko",
        "url": "https://www.yelp.com/biz/gary-danko-san-francisco",
        "rating": 4.5,
        "review_count": 6149,
        "price": "$$$$",
        "categories": [
          { "alias": "newamerican", "title": "New American" },
          { "alias": "french", "title": "French" }
        ],
        "address": {
          "line1": "800 N Point St",
          "city": "San Francisco"
        },
        …
      },
      …
    ],
    "has_more": true,
    "next_page": 2
  },
  "meta": {
    "endpoint_family": "business_search",
    "billable": true
  }
}

The alias is the value you pass as business later. When has_more is true, request the next page by sending page=2, the value in next_page.

How do you get one business's details?

Call GET /v1/yelp/business with the business alias in business. It takes no other parameters, and the value can be up to 160 characters. Use it when you already know which business you want and don't need a search first.

curl "https://api.perceptlayer.com/v1/yelp/business?business=gary-danko-san-francisco" \
  -H "X-API-Key: $API_KEY"

We don't have a recorded response for this endpoint to quote here, so the Yelp Business endpoint page is the place to see the fields. Run the call in its playground with your own key and you'll see the live response. The playground runs a real call with your key.

How do you get Yelp reviews as JSON?

Call GET /v1/yelp/reviews with business, and optionally sort, rating and after. The response includes the business, its review_count, a reviews array and paging fields. Each review carries a rating, text, language, timestamp and author details, plus helpful_count and photos when the review has them.

curl "https://api.perceptlayer.com/v1/yelp/reviews?business=gary-danko-san-francisco&sort=newest" \
  -H "X-API-Key: $API_KEY"

An excerpt of the recorded response, with the author details trimmed:

{
  "success": true,
  "data": {
    "business": {
      "encid": "WavvLdfdP6g8aZTtbBQHTw",
      "alias": "gary-danko-san-francisco",
      "name": "Gary Danko",
      "url": "https://www.yelp.com/biz/gary-danko-san-francisco"
    },
    "review_count": 6149,
    "total": 6150,
    "reviews": [
      {
        "id": "4qYbbI9JbtCDUOtQRcJfDA",
        "url": "https://www.yelp.com/biz/gary-danko-san-francisco?hrid=4qYbbI9JbtCDUOtQRcJfDA",
        "rating": 5,
        "text": "The staff is top notch.\nI really like the way their menu works, …",
        "language": "en",
        "created_at": "2026-10-22T21:21:22Z",
        "author": { … }
      },
      …
    ],
    "has_more": true,
    "next_after": "eyJ2ZXJzaW9uIjoxLCJ0eXBlIjoib2Zmc2V0Iiwib2Zmc2V0Ijo5fQ"
  },
  "meta": {
    "endpoint_family": "business_reviews",
    "billable": true
  }
}

Review text in this sample is cut off with an ellipsis, so treat it as the text as returned by the call, not a guaranteed full review. Reviews are public content written by Yelp users. If you store them, decide what personal data you actually need; the author fields are rarely required for analysis.

How do you page through all the reviews?

Pass the next_after value from one response as after in the next request, and stop when has_more is false. Each page is a separate call at 1 credit, so reading a business with thousands of reviews takes many calls. Work out the page count before you start a loop.

import os
import requests

url = "https://api.perceptlayer.com/v1/yelp/reviews"
headers = {"X-API-Key": os.environ["API_KEY"]}
params = {"business": "gary-danko-san-francisco", "sort": "newest"}

reviews = []
for _ in range(5):  # cap the pages, each one costs a credit
    r = requests.get(url, headers=headers, params=params, timeout=30)
    r.raise_for_status()
    data = r.json()["data"]
    reviews.extend(data["reviews"])
    if not data["has_more"]:
        break
    params["after"] = data["next_after"]

print(len(reviews))

The cap of 5 pages keeps a bug from spending your balance. For safe loop patterns, including what to do after a timeout, see paginating a web data API in Python and retrying calls without paying twice. A request whose reply was lost may have been billed, because requests have no idempotency key.

What does it cost?

Every call to the three endpoints costs 1 credit when it succeeds, and nothing when it fails. A failed call returns X-Credits-Used: 0, and successful responses carry X-Credits-Used and X-Credits-Remaining headers so you can track the balance. The credits docs explain the accounting.

A worked example for a monitoring job that checks the newest reviews of 500 restaurants:

• Find each business once: 500 searches × 1 credit = 500 credits.
• Read the newest reviews page for each, once a week: 500 calls × 1 credit = 500 credits a run.
• Four weekly runs: 4 × 500 = 2,000 credits, plus the 500 for the initial searches.

That is 2,500 credits for the first month. The free tier gives 1,000 credits a month after you verify an email address, no credit card, so this job needs a prepaid pack. Packs start at 10,000 credits and last 12 months. See pricing for what credits cost. If you already store the aliases, skip the searches and the first month is 2,000 credits.

Rate limits are per account and counted per minute. Free accounts get 1 request a second, and a 429 response carries a Retry-After header. Details are in the rate limits docs and error codes.

When is Yelp's official API the better fit?

Yelp has its own developer API, and for a small project it can be the simpler choice. Its documentation describes a reviews endpoint that returns up to three review excerpts for a business (Yelp Places API docs, 2026). If all you need is a few excerpts per business, that limit may not matter for your project.

Choose the Perceptlayer endpoints when you need more than a few excerpts: sorting reviews by newest or lowest, filtering by rating, or paging through the review history of many businesses. They also fit when you want Yelp next to other sources under one key. For the other review sources in the catalogue, see the guides for Trustpilot reviews, Google Maps reviews and Google Play reviews. Check Yelp's current developer terms at docs.developer.yelp.com before you decide.

Data in this API is collected from publicly available sources and returned as found at the time of the call.

Where do you start?

Get a free API key, then run the search call from this guide in the playground on the Yelp API page or paste the cURL into a terminal. The key goes in the X-API-Key header, as the authentication docs describe. If you're wiring this into an agent instead, the AI agents docs cover the MCP server.

yelpreviewslocal businesssearchjson