# Yelp Search API (`johnvc/yelp-search-api`) Actor

Scrape Yelp search results - ranked local business listings with name, categories, star rating, and review count. Search by location and term or paste a Yelp search URL. Filter by category, sort by rating or review count, paginate, and get the place IDs that feed the Details and Reviews APIs.

- **URL**: https://apify.com/johnvc/yelp-search-api.md
- **Developed by:** [John](https://apify.com/johnvc) (community)
- **Categories:** Lead generation, SEO tools, Developer tools
- **Stats:** 16 total users, 12 monthly users, 100.0% runs succeeded, 6 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $0.01 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 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](https://docs.apify.com/platform/integrations/mcp). 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](https://claude.ai/referral/uIlpa7nPLg) (free trial) and [Claude Cowork](https://claude.ai/referral/uIlpa7nPLg) (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):

```json
{
  "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](https://docs.apify.com/platform/integrations/mcp).

#### 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](https://docs.apify.com/platform/integrations/x402).
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](https://mcp.apify.com/?tools=actors,docs,johnvc/yelp-search-api) and it can
discover, pay for, and run this Actor autonomously. Read the
[Apify x402 announcement](https://apify.com/change-log/pay-for-apify-actors-with-x402?fpr=9n7kx3) 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](https://docs.apify.com/platform/integrations).

**Tasks and Schedules (the core recipe).** Save one [task](https://docs.apify.com/platform/actors/running/tasks) per search you care about (for example "dentists in Brooklyn" or "coffee in Austin"), then attach a [schedule](https://docs.apify.com/platform/schedules) 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](https://apify.com/johnvc/yelp-search-api/examples/find-plumbers-in-chicago-for-lead-generation?fpr=9n7kx3) 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](https://docs.apify.com/platform/integrations/make) and [Zapier](https://docs.apify.com/platform/integrations/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`):

```python
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](https://docs.apify.com/platform/integrations/webhooks) 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](#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)

```json
{
  "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](https://apify.com/johnvc/yelp-search-api?fpr=9n7kx3).
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](https://docs.apify.com/api/v2).
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](https://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](https://apify.com/johnvc/Yelp-Place-API?fpr=9n7kx3): feed the `place_ids` from any search into this Actor to pull full business profiles, hours, and contact details.
- [Yelp Reviews API](https://apify.com/johnvc/Yelp-Reviews-API?fpr=9n7kx3): pull the full review history and ratings for the businesses a search returns, MCP-ready for AI agents.
- [Google Maps Places Scraper](https://apify.com/johnvc/google-maps-places-api?fpr=9n7kx3): cross-reference the same local businesses on Google Maps for a second data source on any lead list.
- [Google Local API](https://apify.com/johnvc/google-local-api?fpr=9n7kx3): capture the Google local pack and business SERPs to compare local rankings against Yelp.

Other Yelp scrapers exist, such as [web\_wanderer/yelp-scraper](https://apify.com/web_wanderer/yelp-scraper?fpr=9n7kx3), 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](https://docs.apify.com/platform/integrations/mcp).

#### 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](https://apify.com/johnvc/Yelp-Reviews-API?fpr=9n7kx3) or [Yelp Business Details API](https://apify.com/johnvc/Yelp-Place-API?fpr=9n7kx3) 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](https://docs.apify.com/platform/schedules): save a [task](https://docs.apify.com/platform/actors/running/tasks) 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](https://en.wikipedia.org/wiki/Web_scraping) returns messy HTML you have to parse yourself. This Actor gives you the clean, structured result of a purpose-built [API](https://en.wikipedia.org/wiki/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](https://www.yelp.com/) 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](https://docs.apify.com/platform/integrations): [Make](https://docs.apify.com/platform/integrations/make), [Zapier](https://docs.apify.com/platform/integrations/zapier), [Slack](https://docs.apify.com/platform/integrations/slack), the n8n community node, and [webhooks](https://docs.apify.com/platform/integrations/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](https://docs.apify.com/api/v2), or the Actor's own [API tab](https://apify.com/johnvc/yelp-search-api/api?fpr=9n7kx3).

#### 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](https://mcp.apify.com/) with the Actor-specific URL `https://mcp.apify.com/?tools=actors,docs,johnvc/yelp-search-api`. In [Claude Code](https://claude.ai/referral/uIlpa7nPLg) (free trial) or [Claude Cowork](https://claude.ai/referral/uIlpa7nPLg) (free trial) your agent can then answer questions like "find the best-rated tacos in Austin" with live listings. See the [Apify MCP docs](https://docs.apify.com/platform/integrations/mcp).

#### 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](https://apify.com/johnvc/Yelp-Place-API?fpr=9n7kx3) for full profiles and contact info, and into the [Yelp Reviews API](https://apify.com/johnvc/Yelp-Reviews-API?fpr=9n7kx3) for the complete review history. To cross-reference the same businesses on another map, use the [Google Maps Places Scraper](https://apify.com/johnvc/google-maps-places-api?fpr=9n7kx3).

#### 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](https://blog.apify.com/is-web-scraping-legal/).

### n8n integration

Available as an n8n community node, **[n8n-nodes-yelp-api](https://www.npmjs.com/package/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](https://apify.com/johnvc/yelp-search-api/examples/find-plumbers-in-chicago-for-lead-generation?fpr=9n7kx3) - Build a local leads list of plumbers with rating, reviews, price, categories, and neighborhood.
- [Find dentists in Brooklyn for lead generation](https://apify.com/johnvc/yelp-search-api/examples/find-dentists-in-brooklyn-for-lead-generation?fpr=9n7kx3) - Collect Brooklyn dentist listings for sales outreach.
- [Find dentists by ZIP code for B2B lead lists](https://apify.com/johnvc/yelp-search-api/examples/find-dentists-by-zip-code-for-b2b-lead-lists?fpr=9n7kx3) - Target a single ZIP code to build a focused B2B dentist leads list.
- [Find the best restaurants in Newark by rating](https://apify.com/johnvc/yelp-search-api/examples/find-the-best-restaurants-in-newark?fpr=9n7kx3) - Rank Newark restaurants by rating for market research.
- [Find the best restaurants in Oakland by rating](https://apify.com/johnvc/yelp-search-api/examples/find-the-best-restaurants-in-oakland?fpr=9n7kx3) - Rank Oakland restaurants by rating for market research.
- [Extract Yelp Business Leads From a Search URL](https://apify.com/johnvc/yelp-search-api/examples/extract-yelp-business-leads-from-a-search-url?fpr=9n7kx3) - Paste a Yelp search URL and get the business list back with name, categories, rating, review count, and place IDs.
- [Find the Best Restaurants in San Francisco on Yelp](https://apify.com/johnvc/yelp-search-api/examples/find-the-best-restaurants-in-san-francisco?fpr=9n7kx3) - Rank San Francisco restaurants for market research.
- [Find the Best Restaurants in Las Vegas on Yelp](https://apify.com/johnvc/yelp-search-api/examples/find-the-best-restaurants-in-las-vegas?fpr=9n7kx3) - Rank Las Vegas restaurants for market research.
- [Find the Best Restaurants in San Diego on Yelp](https://apify.com/johnvc/yelp-search-api/examples/find-the-best-restaurants-in-san-diego?fpr=9n7kx3) - Rank San Diego restaurants for market research.
- [Build a Coffee Shop Dataset From Yelp by City](https://apify.com/johnvc/yelp-search-api/examples/build-a-coffee-shop-dataset-from-yelp-by-city?fpr=9n7kx3) - Build a coffee shop list for any city, ready for CSV, JSON, or Excel.

***

### 🌐 About Alpha OSINT

This Actor is part of [Alpha OSINT](https://www.alphaosint.com), toolset of financial and operations data sources and APIs.
See the [Yelp Search API source page](https://www.alphaosint.com/sources/yelp-search-api/) for related tools and use cases.
For support or requests for this actor, please start a ticket [directly on our support page](https://apify.com/johnvc/yelp-search-api/issues/open?fpr=9n7kx3).

Last Updated: 2026.08.04

# Actor input Schema

## `search_url` (type: `string`):

Paste a full Yelp search results URL (e.g. 'https://www.yelp.com/search?find\_desc=coffee\&find\_loc=New+York%2C+NY'). The search term, location, category, sort order, attribute, and area filters are read from the URL, and a regional domain is detected from the address, so a www.yelp.co.uk URL searches the UK site. Values from the URL take precedence over the individual fields below; fields the URL does not contain still apply. Provide either this URL or the Location field. The page offset ('start') in the URL is ignored - use Maximum Pages instead. Optional.

## `search_term` (type: `string`):

Set the Yelp search query (the 'find\_desc' box). Examples: 'coffee', 'plumbers', 'best pizza', 'dentists'. Optional - leave blank to browse all businesses in the location. Any term valid in Yelp search is accepted.

## `location` (type: `string`):

Set the geographic location to search in (the Yelp 'find\_loc' box). Accepts a city and state, a full address, or a ZIP code (e.g. 'New York, NY', 'Austin, Texas', '94103'). Required unless you paste a Yelp Search URL above.

## `category_filter` (type: `string`):

Restrict results to a Yelp category alias (the 'cflt' value). Examples: 'restaurants', 'coffee', 'dentists', 'plumbers'. Optional. Valid aliases are surfaced in the 'filters.category' object of any result.

## `sort_by` (type: `string`):

Order the results. 'recommended' is the Yelp default; 'rating' sorts by highest rated; 'review\_count' sorts by most reviewed. Optional.

## `attrs` (type: `string`):

Refine results by price and feature attributes (the 'attrs' value). Examples: 'RestaurantsPriceRange2.2' for $$, 'ActiveDeal' for deals, 'BusinessParking.validated'. Comma-separate multiple values. Optional. Valid values are surfaced in the 'filters.price' and 'filters.features' objects of any result.

## `radius_filter` (type: `string`):

Narrow results to a distance radius or a neighborhood (the 'l' value). Cannot combine both. Optional. Valid values are surfaced in the 'filters.distance' and 'filters.neighborhoods' objects of any result.

## `yelp_domain` (type: `string`):

Choose which regional Yelp domain to search. 41 domains are supported, e.g. 'www.yelp.com' (US), 'www.yelp.ca' (Canada), 'www.yelp.co.uk' (UK), 'www.yelp.fr' (France), 'www.yelp.de' (Germany), 'www.yelp.com.au' (Australia), 'www.yelp.co.jp' (Japan). Multilingual countries use a language prefix instead of 'www', e.g. 'fr.yelp.ca' for French Canada or 'zh.yelp.com.hk' for Hong Kong. A short form like 'yelp.co.uk' is accepted and expanded for you. Pair the domain with a matching location ('London' with www.yelp.co.uk) for local results. A regional domain is also detected automatically from a pasted search URL. Optional - defaults to www.yelp.com. The full list is in the README.

## `max_pages` (type: `integer`):

Set the maximum number of result pages to fetch (1-indexed). Each page holds about 10 businesses. Set 0 for unlimited, bounded by a safety cap of 20 pages. Default: 1. Each fetched page is billed separately under pay-per-event.

## Actor input object example

```json
{
  "search_term": "coffee",
  "location": "New York, NY",
  "yelp_domain": "www.yelp.com",
  "max_pages": 1
}
```

# Actor output Schema

## `allResults` (type: `string`):

Complete dataset with every page returned by the run. Each item is one page and contains organic\_results, ads\_results, inline\_ads, filters, and search metadata.

## `businessListings` (type: `string`):

Filtered view focused on the organic\_results array - the ranked Yelp businesses for the query, with rating, reviews, price, categories, phone, neighborhood, and place\_ids.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "search_term": "coffee",
    "location": "New York, NY",
    "yelp_domain": "www.yelp.com"
};

// Run the Actor and wait for it to finish
const run = await client.actor("johnvc/yelp-search-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "search_term": "coffee",
    "location": "New York, NY",
    "yelp_domain": "www.yelp.com",
}

# Run the Actor and wait for it to finish
run = client.actor("johnvc/yelp-search-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "search_term": "coffee",
  "location": "New York, NY",
  "yelp_domain": "www.yelp.com"
}' |
apify call johnvc/yelp-search-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=johnvc/yelp-search-api",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/LkdRlXNXYaYcO7f01/builds/bPsedrihzhmdSNbba/openapi.json