# YellowPages Scraper - US Business Leads (`scrapesage/yellowpages-scraper`) Actor

Scrape YellowPages.com for US local businesses - name, phone, full street address, website, categories, star rating, review count and years in business. Search any trade in any city or ZIP.

- **URL**: https://apify.com/scrapesage/yellowpages-scraper.md
- **Developed by:** [Scrape Sage](https://apify.com/scrapesage) (community)
- **Categories:** Lead generation, Other, Agents
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$2.00 / 1,000 business scrapeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## YellowPages Scraper - US Business Leads

Turn any trade + location into a clean list of US business leads from YellowPages.com. Search by category
and city (or ZIP), or paste YellowPages search URLs directly, and get one structured row per business -
name, phone, website, full address, categories, rating and more - ready for a CRM, a call list or outreach.

### What you get per business

| Group | Fields |
|---|---|
| Identity | `name`, `ypId`, `listingId`, `yellowPagesUrl` |
| Contact | `phone` (~100%), `website` (~99%) |
| Address | `street`, `city`, `state`, `postalCode`, `fullAddress` (~95-100%) |
| Classification | `categories[]`, `primaryCategory` (~100%) |
| Reputation | `rating`, `reviewCount`, `yearsInBusiness` |
| Context | `openStatus`, `snippet`, `isClaimed`, `isAd`, `listingType`, `rank`, `page` |

### Input

```json
{
  "searchTerms": ["plumbers", "electricians"],
  "location": "Chicago, IL",
  "maxItems": 200
}
```

- **Search terms + location** - a trade and a city (`"Chicago, IL"`) or a ZIP code, or
- **Search URLs** - paste YellowPages.com search result URLs directly.
- **Filters** - exclude sponsored results (`excludeAds`), require a phone, require a website, or set a
  minimum star rating.

### Reliability

YellowPages sits behind Cloudflare, so this is a full browser actor built to clear it: it opens a fresh
browser context per attempt and waits for the challenge to pass rather than using a fixed timeout, with a
generous retry budget. A run that genuinely cannot get through emits nothing, bills **$0**, and says so in
the status message - you are never charged for a blocked run.

### Honest limits (what the source does and does not carry)

- **`rating` ~27% / `reviewCount` ~18%.** Most YellowPages listings have never been reviewed - this is the
  source, not the parser (on a full page it reads the value from every card that carries one). Density
  depends on the trade: dentists ~60%, restaurants ~48%, plumbers ~21%.
- **`yearsInBusiness` ~35%, `openStatus` ~56%, `snippet` ~54%** are owner-supplied profile fields; unclaimed
  listings simply have none.
- **Sponsored listings are kept, not hidden**, and flagged with `isAd`. A sponsored service-area business
  often has no street address ("Serving the Chicago area") - that text is preserved rather than dropped. Set
  `excludeAds: true` for organic listings only.
- **Search-page data only** - no per-business detail-page crawl, so no opening-hours table and no review
  text.

### Pricing

**$0.002 per business, no start fee.** Only rows you actually receive are billed; a blocked run costs
nothing.

### Output views

- **Businesses** - the full record.
- **Call list** - name, phone, street, city, state, ZIP, category, rating - ready to dial.

### Use with AI assistants (MCP)

Available through the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp) - an agent can
pull a fresh list of local businesses (with phone and website) for a trade and city on demand.

# Actor input Schema

## `searchTerms` (type: `array`):

What to look for, exactly as you would type it into YellowPages - for example plumber, dentist, roofing contractor. One search per term.

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

City and state ("Chicago, IL") or a ZIP code ("60601"). Applies to every search term.

## `startUrls` (type: `array`):

Paste YellowPages search URLs directly instead of using search terms. When set, Search terms and Location are ignored.

## `maxResults` (type: `integer`):

Stop after this many businesses in total. You are only charged for businesses actually saved.

## `maxPagesPerSearch` (type: `integer`):

How deep to page through each search. A YellowPages page holds about 30 businesses plus ads.

## `excludeAds` (type: `boolean`):

Skip paid placements. Sponsored businesses are real businesses but usually have no street address, so leave this off if you want maximum volume and use the isAd field to sort them yourself.

## `onlyWithPhone` (type: `boolean`):

Drop businesses that have no phone number listed.

## `onlyWithWebsite` (type: `boolean`):

Drop businesses that have no website listed.

## `minRating` (type: `integer`):

Keep only businesses rated at least this many stars. 0 keeps everything, including unrated businesses.

## `proxyConfiguration` (type: `object`):

YellowPages sits behind Cloudflare. US residential proxies are strongly recommended - the defaults below are the tested setup.

## Actor input object example

```json
{
  "searchTerms": [
    "plumber"
  ],
  "location": "Chicago, IL",
  "maxResults": 100,
  "maxPagesPerSearch": 3,
  "excludeAds": false,
  "onlyWithPhone": false,
  "onlyWithWebsite": false,
  "minRating": 0,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

## `results` (type: `string`):

Every scraped business as a JSON item in the default dataset.

# 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 = {
    "searchTerms": [
        "plumber"
    ],
    "location": "Chicago, IL"
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapesage/yellowpages-scraper").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 = {
    "searchTerms": ["plumber"],
    "location": "Chicago, IL",
}

# Run the Actor and wait for it to finish
run = client.actor("scrapesage/yellowpages-scraper").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "searchTerms": [
    "plumber"
  ],
  "location": "Chicago, IL"
}' |
apify call scrapesage/yellowpages-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,scrapesage/yellowpages-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/4gcxuX1krHbNZmB3A/builds/XL8sACz9yMRBk5a7Q/openapi.json