Yelp Search API | Local Business Listings, Ratings & Reviews (MCP-ready)

Scrape Yelp search results and get clean JSON back. Ranked local business listings with rating, reviews, price, categories, phone, neighborhood, and place IDs, plus ads and the available refinement filters. Pay per page. MCP-ready for Claude, ChatGPT, Cursor, and other AI agents.

Pass a search term and a location and the Actor returns the same ranked business listings Yelp shows on its search results page: business names, ratings, review counts, price tiers, categories, neighborhoods, open state, snippets, service options (delivery, takeout, outdoor dining), thumbnails, and the Yelp place_ids you need to pull full details or reviews. Sponsored placements (ads and inline ad carousels) and the full set of Yelp refinement filters (distance, neighborhoods, price, categories, features) come back too.

This is a Yelp search results API: predictable per-page pricing, structured JSON, and no browser automation or captchas. It is the entry point of a 3-actor Yelp suite - feed the place_ids it returns into the Yelp Business Details API and the Yelp Reviews API.

---

What this Actor returns

• Ranked business listings (organic_results) - position, title, place_ids, link, categories, price ($-$$$$), rating, review count, neighborhoods, open state, snippet, highlights, service options, thumbnail.
• Ad placements (ads_results, inline_ads) - sponsored businesses with block position and call-to-action buttons.
• Available filters (filters) - the valid distance, neighborhood, price, category, and feature values you can pass back in as radius_filter, category_filter, or attrs to refine the next search.
• Run metadata - echoed search parameters, page number, pagination state, and a per-page timestamp.

Each page of results is one dataset item and one billable event.

---

Use with Claude, ChatGPT, Cursor & other AI agents (MCP)

This Actor is a first-class tool on the Apify MCP Server. Any MCP-compatible AI agent - Claude (Desktop, Web, Code), ChatGPT, Cursor, VS Code, Cline, Windsurf, Kilo Code, Opencode, Glama - can discover and call it in natural language.

What an AI agent does with this:

User: "Find the highest-rated coffee shops in Williamsburg, Brooklyn."

Agent calls search-actors("yelp search") on the Apify MCP server, picks this Actor, calls it with {"search_term": "coffee", "location": "Brooklyn, NY", "sort_by": "rating", "max_pages": 2}, gets the ranked listings back, and returns a short list with ratings and review counts.

New to Claude? Claude Code and the Claude desktop app (which runs Cowork) both come with a free trial: https://claude.ai/referral/uIlpa7nPLg

Quick setup - Claude Desktop

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "apify": {
      "command": "npx",
      "args": ["-y", "@apify/actors-mcp-server"],
      "env": {
        "APIFY_TOKEN": "YOUR_APIFY_API_TOKEN"
      }
    }
  }
}

Restart Claude Desktop, then ask something like "Find vegan restaurants in Austin with 4.5+ stars." Claude discovers this Actor, asks permission to call it, and returns structured results.

Quick setup - Cursor / VS Code / Cline / Windsurf

These editors support dynamic tool discovery, so after the first call this Actor is registered as a named tool for the rest of the session. Point your MCP client at:

https://mcp.apify.com

…with header Authorization: Bearer YOUR_APIFY_API_TOKEN. Full setup: Apify MCP integration docs.

Quick setup - ChatGPT (and other static MCP clients)

ChatGPT, Gemini CLI, and Amazon Q connect through the same https://mcp.apify.com endpoint and call this Actor via the generic call-actor tool. Same result, just no session-level tool registration.

---

Use cases

• Local lead generation - "Pull every plumber in {city} with under 50 reviews so I can pitch them."
• Local SEO & rank tracking - "Where does {business} rank on Yelp for 'best tacos' across these 20 cities?"
• Market & competitor research - rating, review count, and price distribution for a category in a market.
• Lead lists for sales - build a list of businesses by category and location with phone numbers and neighborhoods.
• Feeding the Yelp suite - harvest place_ids to pull full business profiles and reviews with the companion Actors.

---

Input parameters

Parameter	Type	Required	Default	Description
location	string	Yes	-	City + state, full address, or ZIP (e.g. New York, NY).
search_term	string	No	-	What to search for (e.g. coffee, plumbers). Blank = browse all in the location.
category_filter	string	No	-	Yelp category alias (e.g. restaurants, coffee).
sort_by	string (enum)	No	recommended	recommended, rating, or review_count.
attrs	string	No	-	Price/feature filters (e.g. RestaurantsPriceRange2.2, ActiveDeal).
radius_filter	string	No	-	Distance radius or neighborhood value (cannot combine both).
yelp_domain	string	No	yelp.com	Regional Yelp domain.
max_pages	integer	No	1	Pages to fetch (~10 businesses each). 0 = unlimited (cap 20).

Valid values for category_filter, attrs, and radius_filter are returned in the filters object of every result, so you can run a broad search first and then refine.

---

Example output (one item per page)

{
  "page_number": 1,
  "search_timestamp": "2026-05-26T10:30:00.123456",
  "search_parameters": { "find_desc": "Coffee", "find_loc": "New York, NY", "sortby": "rating", "max_pages": 1 },
  "search_metadata": { "pages_processed": 1, "max_pages_set": 1, "pagination_limit_reached": false, "total_results_estimate": null },
  "organic_results": [
    {
      "position": 1,
      "place_ids": ["K6fkejf2ZBUdlsVrm5RbrA", "kore-coffee-new-york-2"],
      "title": "Kore Coffee",
      "link": "https://www.yelp.com/biz/kore-coffee-new-york-2",
      "categories": [{ "title": "Coffee & Tea", "link": "https://www.yelp.com/search?cflt=coffee" }],
      "rating": 5,
      "reviews": 13,
      "neighborhoods": "Chinatown",
      "snippet": "Nice small cozy coffee place...",
      "thumbnail": "https://s3-media0.fl.yelpcdn.com/bphoto/.../348s.jpg"
    }
  ],
  "ads_results": [],
  "inline_ads": [],
  "filters": { "price": [{ "text": "$", "value": "RestaurantsPriceRange2.1" }], "category": [], "distance": [], "features": [] },
  "pagination": { "start": 0 }
}

The place_ids array (encoded ID and human-readable alias) is what you feed into the Yelp Business Details API and Yelp Reviews API.

---

Pricing

This Actor uses transparent pay-per-event pricing:

Event	Price	When
Setup	$0.02	Once per run
Page processed	$0.02	Per page of results fetched (~10 businesses)

A typical 1-page search costs about $0.04 total. A 5-page run costs about $0.12. You are billed per page regardless of how many businesses appear, so pricing is predictable.

---

How to get started

1. Open the Actor on the Apify Store.
2. Enter a location (and optionally a search_term), set max_pages, and click Start.
3. Read results from the dataset (JSON, CSV, Excel) or via the Apify API.
4. Or call it from any MCP-compatible AI agent using the setup above.

---

Code example (Python + MCP)

Want a runnable quick-start? The public example repo has a Python (uv) script plus MCP install guides for Claude (Desktop, Code, Web) and Cursor:

github.com/johnisanerd/Apify-Yelp-API

It shows how the Yelp Search, Business Details, and Reviews APIs chain together - a search returns the place_ids that feed the other two.

FAQ / Troubleshooting

• No results? Make sure location is a real place Yelp recognizes (city + state works best). Try a broader search_term or remove category_filter.
• How do I get more than ~10 results? Increase max_pages. Each page adds about 10 businesses.
• Where do place_ids come from / what are they for? Every listing includes a place_ids array. Use either value with the Yelp Business Details API or Yelp Reviews API.
• What values can I use for filters? Run any search, then read the filters object - it lists the valid category_filter, attrs, and radius_filter values for that query.
• Is this reliable? Yes - it calls a structured data API, not a headless browser, so there are no captchas or layout breakages.

Learn more about the Apify MCP integration.

Last Updated: 2026.05.29