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

Paste a Yelp search results URL - or fill in a term and a location - 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.

Run the search on yelp.com, copy the address bar into search_url, 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.

The search term, location, category filter, sort order, attribute filters, and area filter are all read out of a pasted URL, so https://www.yelp.com/search?find_desc=coffee&find_loc=New+York%2C+NY&sortby=rating&cflt=restaurants&attrs=RestaurantsPriceRange2.2 needs nothing else filled in. Values in the URL take precedence over the individual fields, and the fields still supply anything the URL leaves out. The page offset (start) in the URL is deliberately ignored - control how deep you go with max_pages. Filling in location and search_term by hand works exactly as before; supply either location or search_url.

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 (free trial) and Claude Cowork (free trial), which runs in the Claude desktop app, both come with a free trial.

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.

---

💸 Pay per run with crypto (x402)

The Yelp Search API supports agentic payments via the x402 protocol. AI agents and MCP clients can pay for runs in USDC (on Base) with no Apify account or API token needed: point your agent at the Apify MCP server and it can discover, pay for, and run this Actor autonomously. Read the Apify x402 announcement for details.

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.

---

🔌 Integrations: Automate Local Lead Generation

A single run answers one question ("who are the top-rated plumbers in Chicago right now?"). The real value comes from running the Yelp Search API on a schedule, so fresh local business listings for your local lead generation, local SEO, and market research land in your stack automatically. See the full list of Apify platform integrations.

Tasks and Schedules (the core recipe). Save one task per search you care about (for example "dentists in Brooklyn" or "coffee in Austin"), then attach a schedule from the Actor's Actions, then Schedule menu. Useful cron strings: 0 7 * * * (daily at 7 AM), 0 */6 * * * (every six hours), 0 9 * * 1 (Mondays). One schedule can trigger many saved tasks at once, so a whole watchlist of cities and categories refreshes in a single run. The Find plumbers in Chicago for lead generation task is a ready-made starting point.

n8n. This API ships an n8n community node (see the n8n integration section below). A four-step monitor: Schedule Trigger, then the Yelp Search API node, then a Filter on reviews (for example under 50 reviews for fresh leads), then Slack or email.

Make and Zapier. The same pattern works no-code with Make and Zapier: trigger on a schedule, run the Actor, then route the listings wherever your team works.

Store the history (Supabase). Send each run's listings into a table so a lead list accumulates across cities and dates. No-code: the n8n Actor node, then a Supabase node. Or in Python, flattening the organic_results array from each page (every listing carries title, place_ids, rating, reviews, neighborhoods, and link):

from apify_client import ApifyClient
from supabase import create_client

apify = ApifyClient("YOUR_APIFY_TOKEN")
supabase = create_client("YOUR_SUPABASE_URL", "YOUR_SUPABASE_KEY")

run = apify.actor("johnvc/yelp-search-api").call(run_input={
    "search_term": "plumbers",
    "location": "Chicago, IL",
    "sort_by": "review_count",
    "max_pages": 3,
})

leads = []
for page in apify.dataset(run["defaultDatasetId"]).iterate_items():
    for biz in page.get("organic_results", []):
        leads.append({
            "name": biz.get("title"),
            "place_id": (biz.get("place_ids") or [None])[0],
            "rating": biz.get("rating"),
            "reviews": biz.get("reviews"),
            "neighborhood": biz.get("neighborhoods"),
            "url": biz.get("link"),
        })
supabase.table("yelp_leads").upsert(leads).execute()

MCP and AI agents. Add the Yelp Search API as a tool in Claude or Cursor through the Apify MCP server so an agent can pull ranked listings in natural language (see the Use with Claude section above).

Webhooks. For anything custom, fire an Apify webhook on ACTOR.RUN.SUCCEEDED to push each run's dataset into your own service.

---

Input parameters

Parameter	Type	Required	Default	Description
search_url	string	No	-	A full Yelp search results URL pasted from your browser (e.g. https://www.yelp.com/search?find_desc=coffee&find_loc=New+York%2C+NY). The search term, location, category, sort order, attribute filters, and area filter are read out of it, and values in the URL take precedence over the fields below. The page offset (start) is ignored - use max_pages.
location	string	Yes, unless search_url is set	-	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	www.yelp.com	Regional Yelp domain to search - e.g. www.yelp.co.uk, www.yelp.fr, fr.yelp.ca. A short form like yelp.co.uk is expanded for you. See Regional Yelp domains.
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.

A JSON schema cannot express "one of these two", so location is no longer flagged as required in the input form and the requirement is checked when the run starts instead: a run with neither location nor search_url pushes a ValidationError item saying which one to supply. Pasting a /biz/ business URL into search_url also returns a ValidationError, pointing you at the Yelp Business Details API or Yelp Reviews API.

---

Regional Yelp domains

Set yelp_domain to search a Yelp site outside the US. 41 domains are supported.

Use the full host, including the www. or language prefix - www.yelp.co.uk, not yelp.co.uk. A short form is accepted and expanded for you, so yelp.co.uk works too, but the expanded value is what gets sent. Multilingual countries have no www host at all: Switzerland, Belgium, Malaysia, Hong Kong, the Philippines, and Finland use a language prefix instead. An unrecognized value is ignored with a warning and the run falls back to www.yelp.com rather than failing.

Pair the domain with a location on that site - www.yelp.co.uk with London, www.yelp.co.jp with Tokyo. The domain alone does not relocate the search.

Country	yelp_domain values
Argentina	www.yelp.com.ar
Australia	www.yelp.com.au
Austria	www.yelp.at
Belgium	en.yelp.be (English), fr.yelp.be (French), nl.yelp.be (Dutch)
Brazil	www.yelp.com.br
Canada	www.yelp.ca (English), fr.yelp.ca (French)
Chile	www.yelp.cl
Czechia	www.yelp.cz
Denmark	www.yelp.dk
Finland	fi.yelp.fi (Finnish), sv.yelp.fi (Swedish)
France	www.yelp.fr
Germany	www.yelp.de
Hong Kong	en.yelp.com.hk (English), zh.yelp.com.hk (Chinese)
Ireland	www.yelp.ie
Italy	www.yelp.it
Japan	www.yelp.co.jp
Malaysia	ms.yelp.my (Malay), en.yelp.my (English)
Mexico	www.yelp.com.mx
Netherlands	www.yelp.nl
New Zealand	www.yelp.co.nz
Norway	www.yelp.no
Philippines	en.yelp.com.ph (English), fil.yelp.com.ph (Filipino)
Poland	www.yelp.pl
Portugal	www.yelp.pt
Singapore	www.yelp.com.sg
Spain	www.yelp.es
Switzerland	de.yelp.ch (German), en.yelp.ch (English), fr.yelp.ch (French), it.yelp.ch (Italian)
Taiwan	www.yelp.com.tw
Turkey	www.yelp.com.tr
United Kingdom	www.yelp.co.uk
United States	www.yelp.com

---

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_url": null },
  "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. search_parameters.search_url echoes the URL you pasted, and is null when you filled in the fields instead.

---

Pricing

This Actor uses transparent pay-per-event pricing:

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

A typical 1-page search costs about $0.02 total. A 5-page run costs about $0.06. You are billed per page regardless of how many businesses appear, so pricing is predictable. Paid Apify plans get a small per-event discount, so the real total comes in slightly under these figures.

---

How to get started

1. Open the Actor on the Apify Store.
2. Paste a Yelp search results URL into search_url, or 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.

🔗 Related Tools

Building a local business dataset or a lead generation pipeline? These Actors from the same catalog pair naturally with Yelp search results:

• Yelp Business Details API: feed the place_ids from any search into this Actor to pull full business profiles, hours, and contact details.
• Yelp Reviews API: pull the full review history and ratings for the businesses a search returns, MCP-ready for AI agents.
• Google Maps Places Scraper: cross-reference the same local businesses on Google Maps for a second data source on any lead list.
• Google Local API: capture the Google local pack and business SERPs to compare local rankings against Yelp.

Other Yelp scrapers exist, such as web_wanderer/yelp-scraper, but it carries a mixed user rating (about 3.1 of 5) and thin adoption (a couple dozen monthly users). This API is actively maintained and returns clean, structured JSON with predictable per-page pricing and no browser automation.

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.

Can I paste a Yelp search URL instead of filling in the fields?

Yes. Run the search on yelp.com, copy the address bar, and paste it into search_url - for example https://www.yelp.com/search?find_desc=coffee&find_loc=New+York%2C+NY. The Actor reads the search term, location, category, sort order, and price filters out of the URL, and values in the URL take precedence over the individual fields. Provide either search_url or location. Business page URLs (/biz/...) belong in the Yelp Reviews API or Yelp Business Details API instead. The page offset in the URL is ignored - use max_pages to control how many pages you fetch.

Can I schedule the Yelp Search API to run automatically?

Yes, and this is where most of the value is. Any run can be automated on a schedule: save a task with your search_term and location, then open the Actor's Actions menu, then Schedule, and pick a cadence. Common cron strings are 0 7 * * * (daily at 7 AM), 0 */6 * * * (every six hours), and 0 9 * * 1 (Monday mornings). One schedule can trigger many saved tasks, so a full list of cities and categories refreshes together. See the Integrations section above for the complete Tasks and Schedules recipe.

Should I use an API or a web scraper for Yelp?

Both, and this Actor is both. An official Yelp API is rate limited, quota bound, and gated behind an application and key, while a plain web scraper returns messy HTML you have to parse yourself. This Actor gives you the clean, structured result of a purpose-built API: call it yourself or run it no-code, pay per page, no quotas, and get the same ranked JSON every time.

Does Yelp have an API, and do I need a Yelp API key?

Yelp offers its own developer API, but it requires an application, an API key, and comes with quotas and field limits. This Actor needs no Yelp API key: it reads the public Yelp search results page directly and returns structured JSON, with no Yelp quotas to manage. You authenticate only with your Apify token.

Can I integrate this Yelp Scraper with other apps?

Yes. It connects to almost any cloud service through Apify integrations: Make, Zapier, Slack, the n8n community node, and webhooks on ACTOR.RUN.SUCCEEDED for custom actions. See the Integrations section above for full recipes.

Can I use the Yelp Search API with the Apify API?

Yes. The Apify API runs the Actor, schedules it, and fetches datasets, and the apify-client package exists for both Node.js and Python. See the Apify API docs, or the Actor's own API tab.

Can I use this through an MCP server?

Yes. Add the Yelp Search API as a tool in any MCP client (Claude, Cursor, and others) through the hosted Apify MCP server with the Actor-specific URL https://mcp.apify.com/?tools=actors,docs,johnvc/yelp-search-api. In Claude Code (free trial) or Claude Cowork (free trial) your agent can then answer questions like "find the best-rated tacos in Austin" with live listings. See the Apify MCP docs.

How do I track local SEO rankings across multiple locations?

Run one saved task per city or ZIP code with the same search_term and sort_by, then put them all on one schedule. Each run captures where every business ranks in that market, so a multi-location business or an agency can watch local SEO positions over time. Feed the place_ids into the companion Actors below to enrich each business with full details and reviews.

How can I get Yelp reviews and full business details?

Every listing this Actor returns includes a place_ids array. Pass those IDs into the Yelp Business Details API for full profiles and contact info, and into the Yelp Reviews API for the complete review history. To cross-reference the same businesses on another map, use the Google Maps Places Scraper.

Is it legal to scrape Yelp?

Scraping publicly available data is broadly permitted, though you should respect each site's terms and avoid personal data where it is regulated. This Actor reads only the public Yelp search results page. For background, see Apify's overview of the legality of web scraping.

n8n integration

Available as an n8n community node, n8n-nodes-yelp-api (Search Businesses, Get Business Details, and Get Reviews). In n8n: Settings, Community Nodes, install n8n-nodes-yelp-api, then use it in any workflow (it also works as an AI Agent tool).

---

Featured Tasks

Ready-to-run examples that show this API solving a specific problem. Each opens its own setup so you can run it on your account in one click.

• Find plumbers in Chicago for lead generation - Build a local leads list of plumbers with rating, reviews, price, categories, and neighborhood.
• Find dentists in Brooklyn for lead generation - Collect Brooklyn dentist listings for sales outreach.
• Find dentists by ZIP code for B2B lead lists - Target a single ZIP code to build a focused B2B dentist leads list.
• Find the best restaurants in Newark by rating - Rank Newark restaurants by rating for market research.
• Find the best restaurants in Oakland by rating - Rank Oakland restaurants by rating for market research.

---

🌐 About Alpha OSINT

This Actor is part of Alpha OSINT, toolset of financial and operations data sources and APIs. See the Yelp Search API source page for related tools and use cases. For support or requests for this actor, please start a ticket directly on our support page.

Last Updated: 2026.08.04