--- title: "Yelp Reviews API: Business Search and Reviews as JSON" description: "Three Yelp endpoints return search results, business details and reviews as JSON, 1 credit per call. Parameters, a real response and a cost example." url: https://perceptlayer.com/blog/yelp-reviews-api-json --- [Blog](https://perceptlayer.com/blog) / [API guides](https://perceptlayer.com/blog/category/api-guides) # Yelp Reviews API: Business Search and Reviews as JSON 7 Aug 2026 Updated 26 Oct 2026 Perceptlayer 6 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. ## Key takeaways - The [Yelp API](https://perceptlayer.com/apis/yelp) has 3 endpoints, search, business and reviews, and each costs 1 credit per successful call. - Search needs `query` and `location`. Business and reviews need `business`, which is the Yelp alias such as `gary-danko-san-francisco`. - Reviews can be sorted with `sort` (relevance, newest, oldest, highest, lowest, elite) and paged with `after`, using the `next_after` value from the previous response. - Looking up one business, searching for it and reading one page of its reviews costs 3 credits. The free tier gives 1,000 credits a month. - For a small project that needs only a few review excerpts per business, Yelp's official API may be enough. ## 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. | Method | Path | Returns | Credits | Required | Optional | | --- | --- | --- | --- | --- | --- | | GET | `/v1/yelp/search` | Search results | 1 | `query`, `location` | `limit`, `page` | | GET | `/v1/yelp/business` | Business details | 1 | `business` | none | | GET | `/v1/yelp/reviews` | Reviews | 1 | `business` | `sort`, `rating`, `after` | Each endpoint has its own page with a playground: [Search](https://perceptlayer.com/apis/yelp/search), [Business](https://perceptlayer.com/apis/yelp/business) and [Reviews](https://perceptlayer.com/apis/yelp/reviews). Yelp sits in the [Reviews APIs](https://perceptlayer.com/verticals/reviews) 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. ```bash curl "https://api.perceptlayer.com/v1/yelp/search?query=gary+danko&location=San+Francisco%2C+CA" \ -H "X-API-Key: $API_KEY" ``` | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `query` | string | yes | Up to 100 characters | | `location` | string | yes | Up to 100 characters | | `limit` | integer | no | Optional | | `page` | integer | no | Optional; the recorded response returns the next value as `next_page` | This is an excerpt of the recorded response for that request: ```json { "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. ```bash 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](https://perceptlayer.com/apis/yelp/business) 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. ```bash curl "https://api.perceptlayer.com/v1/yelp/reviews?business=gary-danko-san-francisco&sort=newest" \ -H "X-API-Key: $API_KEY" ``` | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `business` | string | yes | Up to 160 characters | | `sort` | string | no | One of `relevance`, `newest`, `oldest`, `highest`, `lowest`, `elite` | | `rating` | integer | no | Optional | | `after` | string | no | Up to 200 characters; the cursor from `next_after` | An excerpt of the recorded response, with the author details trimmed: ```json { "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. ```python 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](https://perceptlayer.com/blog/paginate-web-data-api-python) and [retrying calls without paying twice](https://perceptlayer.com/blog/retry-web-api-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](https://docs.perceptlayer.com/credits) 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](https://perceptlayer.com/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](https://docs.perceptlayer.com/rate-limits) and [error codes](https://docs.perceptlayer.com/errors). ## 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](https://docs.developer.yelp.com/docs/fusion-intro), 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](https://perceptlayer.com/blog/trustpilot-reviews-api), [Google Maps reviews](https://perceptlayer.com/blog/google-maps-reviews-api-parameters) and [Google Play reviews](https://perceptlayer.com/blog/google-play-store-api). Check Yelp's current developer terms at [docs.developer.yelp.com](https://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](https://perceptlayer.com/signup), then run the search call from this guide in the playground on the [Yelp API page](https://perceptlayer.com/apis/yelp) or paste the cURL into a terminal. The key goes in the `X-API-Key` header, as the [authentication docs](https://docs.perceptlayer.com/authentication) describe. If you're wiring this into an agent instead, the [AI agents docs](https://docs.perceptlayer.com/ai-agents) cover the MCP server. ## APIs in this post - [Yelp **1 credit per call** · 3 endpoints](https://perceptlayer.com/apis/yelp) ## Frequently asked questions ### Is there an official Yelp reviews API? Yes. Yelp publishes a developer API with a reviews endpoint. Its documentation says the endpoint returns up to three review excerpts for a business ( [Yelp Places API docs](https://docs.developer.yelp.com/docs/fusion-intro), 2026). That suits small projects. If you need sorting, rating filters and paging through many reviews, the `/v1/yelp/reviews` endpoint here takes `sort`, `rating` and `after`. ### How much does a Yelp reviews call cost? A successful call to `/v1/yelp/reviews`, `/v1/yelp/business` or `/v1/yelp/search` costs 1 credit. Failed calls cost nothing and return `X-Credits-Used: 0`. Reading 10 pages of one business's reviews is 10 calls × 1 credit = 10 credits. The free tier includes 1,000 credits a month, and [pricing](https://perceptlayer.com/pricing) shows what credit packs cost. ### How do I find the business value for Yelp reviews? Run a search with `query` and `location`, then copy the `alias` from a result, for example `gary-danko-san-francisco`. Pass it as `business` to `/v1/yelp/business` or `/v1/yelp/reviews`. The value can be up to 160 characters, and the search response also includes the business URL and `encid`. ### What happens when there are more reviews than one page? The response sets `has_more` to `true` and gives a `next_after` cursor. Send that value as the `after` parameter in your next request to the same endpoint, and repeat until `has_more` is `false`. Each page is one successful call, so it costs 1 credit. Cap your loop so a bug can't spend your balance. ### Can I use this data in an AI agent? Yes. The same key works over MCP at `https://api.perceptlayer.com/mcp`, where `search_endpoints` and `get_endpoint` look up the catalogue for free and `call_endpoint` runs an endpoint for its credits on success only. See the [AI agents docs](https://docs.perceptlayer.com/ai-agents) for setup. ### Should I build a Yelp scraper instead? A Yelp scraper is code you maintain against changing pages, with blocks to handle and Yelp's terms to follow. The search, business and reviews endpoints return named JSON fields for 1 credit per successful call, and failed calls cost nothing. Yelp also runs its own developer API; compare its terms and limits with these endpoints before writing a scraper. yelp reviews local business search json ## More from the blog 1. [API guides](https://perceptlayer.com/blog/category/api-guides) 14 Oct 2026 Perceptlayer 7 min read ## [Google News API: Search News Articles as JSON](https://perceptlayer.com/blog/google-news-api) One GET call to /v1/google-news/news returns articles with title, link, source and ISO date as JSON for 1 credit. Parameters, a real response, cost. 2. [API guides](https://perceptlayer.com/blog/category/api-guides) 13 Oct 2026 Perceptlayer 6 min read ## [Google Patents API: Search Patents and Get Details](https://perceptlayer.com/blog/google-patents-api-search-details) Search Google Patents by keyword, inventor or assignee with one GET call, then fetch full details by patent\_id. Both endpoints cost 1 credit per call. 3. [API guides](https://perceptlayer.com/blog/category/api-guides) 19 Aug 2026 Perceptlayer 8 min read ## [Google Events API: Find Local Events as JSON](https://perceptlayer.com/blog/google-events-api-local-events) Search Google Events as JSON with one GET: q, hl, gl, location and start parameters, a recorded London response, and 1 credit per call.