# Yellow Pages Scraper | 12 Fields, Phone & Website Leads (`themineworks/yellowpages-us`) Actor

Scrape YellowPages.com into clean US business leads: name, phone, full address, categories, website, years in business. Search any vertical by city or ZIP. No login. Pay per result. Works in Claude, ChatGPT and any MCP agent.

- **URL**: https://apify.com/themineworks/yellowpages-us.md
- **Developed by:** [The Mine Works](https://apify.com/themineworks) (community)
- **Categories:** Lead generation, MCP servers
- **Stats:** 3 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 businesses

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/actors/running/actors-in-store.md#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

## Yellow Pages Scraper: 12 Fields, Phone & Website Leads

Pay only for results delivered. [Browse all Actors](https://apify.com/themineworks).

💰 From $1.00 / 1,000 results.

Turn a trade and a city into a callable US lead list: business name, phone, full street address, categories, website and years in business.

### Why use this Yellow Pages scraper

YellowPages.com is still one of the densest sources of US small-business contact data, and unlike a maps scraper it gives you the business's **own website URL** and a **years in business** figure alongside the phone number. Those two fields are what turn a list into a qualified list.

**12 fields per business**, with the address split into street, city, state and ZIP rather than handed back as one string you then have to parse. Phone numbers are normalised to `+1-XXX-XXX-XXXX`.

This actor uses a **real browser**, and the reason is measured rather than assumed. YellowPages is behind Cloudflare and the rule blocks every path, not just search. From one clean residential IP in the same minute: `got-scraping` returned 403 on twelve of twelve attempts across residential, datacenter and no-proxy; two other TLS-impersonating HTTP clients returned 403 on three of three each; a real Chrome on the same IP returned 200 with 84 listings. Cloudflare is gating on JavaScript execution, so no fingerprint tweak fixes it.

Cost is controlled tightly given that: the browser is launched **once** and reused across every page, and images, media, fonts and stylesheets are aborted at the network layer, so only the HTML document crosses the residential proxy.

### Find every plumber in a city

Both `searchTerm` and `location` are required. Location takes the `City, ST` form YellowPages expects.

```json
{
  "searchTerm": "plumbers",
  "location": "Austin, TX",
  "maxResults": 200
}
```

### Build a lead list for a service category

Pagination walks 30 listings per page and de-duplicates across pages, so raising `maxResults` genuinely deepens the list rather than repeating page one.

```json
{
  "searchTerm": "hvac contractors",
  "location": "Phoenix, AZ",
  "maxResults": 500
}
```

### Target a professional services niche

Categories come back as an array, so you can post-filter on the secondary categories YellowPages assigns each listing.

```json
{
  "searchTerm": "personal injury attorney",
  "location": "Chicago, IL",
  "maxResults": 300
}
```

### Pin the run to a specific residential country

US residential is mandatory here; datacenter IPs are 403'd. This is the default spelled out so you can adjust the country or group.

```json
{
  "searchTerm": "dentists",
  "location": "Miami, FL",
  "maxResults": 150,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

### What data you get back

12 fields per business.

| Field | What it is |
| --- | --- |
| `name` | Business name |
| `phone` | Phone, normalised to `+1-XXX-XXX-XXXX` where the digits allow |
| `street` | Street address |
| `city` | City, parsed out of the locality line |
| `state` | Two-letter state code |
| `zip` | ZIP, including ZIP+4 where listed |
| `categories` | Array of YellowPages category labels |
| `website` | The business's own website URL, when they list one |
| `years_in_business` | Years in business as a number, from the YP badge |
| `url` | The YellowPages listing detail URL |
| `search_term` | The term that produced this row |
| `scraped_at` | ISO timestamp of capture |

A final `_type: "summary"` record reports the business count, the charged count, the search term, the location and how many pages were fetched.

### How it works

1. A search URL is built from your term and location and paged with `&page=N`, 30 listings per page, up to a hard ceiling of 50 pages.
2. Each page is fetched in a headless Chromium routed through US residential proxy. A short settle lets any Cloudflare interstitial resolve into the real page before the HTML is read.
3. The HTML is parsed with cheerio against the listing container, with fallback selectors for the layout variants YellowPages has shipped over time.
4. Rows are de-duplicated across pages on YellowPages' own listing id, falling back to the listing URL, then to a name-plus-phone key.
5. If a page comes back blocked, the proxy session is rotated and the page is retried up to three times before pagination stops.

The browser process is closed on every exit path, success or failure, so it can never outlive the run.

### Who uses Yellow Pages data

**Local B2B outbound.** A trade plus a metro is a callable list with a phone number on every row.

**Franchise and territory research.** Count competitors per city and see how long each has been operating via `years_in_business`.

**Website audit prospecting.** `website` is present on some listings and absent on others. The businesses without one are a well-defined agency prospect list.

**Data enrichment.** Match your existing CRM records against name plus phone to fill in addresses and categories.

### What it costs

One pay-per-event charge, `business-scraped`, billed per business that actually lands in your dataset. Your rate depends on your own Apify discount tier:

| Your Apify tier | Per business | Per 1,000 |
| --- | --- | --- |
| FREE | $0.002 | $2.00 |
| BRONZE | $0.0016 | $1.60 |
| SILVER | $0.00125 | $1.25 |
| GOLD / PLATINUM / DIAMOND | $0.001 | $1.00 |

Nothing else is billed. Failed requests, blocked pages, empty searches and error records are never charged, so a run that returns no businesss costs nothing. There is no subscription and no monthly minimum.

### Run it on a schedule

Scheduled runs are the pattern most people end up on: smaller, more frequent runs finish faster, keep the data fresh, and cost exactly the same per record as one big run.

1. On this actor's page, click **... -> Schedule Actor** (or Console -> **Schedules -> Create new**).
2. Pick a frequency. `@daily` suits most standing queries.
3. Your saved input is reused on every run and each run appends to the dataset.
4. Wire the dataset to Google Sheets, Slack, or a webhook from the **Integrations** tab so new rows reach you without you looking.

### FAQ

**Why does this need a residential proxy?**
YellowPages is behind Cloudflare and datacenter IPs are 403'd. US residential is the default and is required.

**Why does it use a browser instead of plain HTTP?**
Because we measured it. Every HTTP client tested, including ones that impersonate Chrome's TLS fingerprint, returned 403 from a clean residential IP, while a real browser on the same IP returned 200 with full listings. Cloudflare is gating on JavaScript execution.

**Isn't a browser on residential expensive?**
It would be if run naively. The browser is launched once and reused across all pages, and images, media, fonts and stylesheets are aborted before they cross the proxy, so only HTML is paid for.

**What format should `location` be in?**
`City, ST`, for example `Austin, TX`. That is what YellowPages' own search expects.

**Do all listings have a website?**
No. `website` is present when the business lists one. Its absence is itself a useful signal for agency prospecting.

**How many results can I get from one search?**
Pagination walks up to 50 pages at 30 listings per page. In practice depth depends on how many listings YellowPages has for that term and city.

**Are phone numbers formatted consistently?**
They are normalised to `+1-XXX-XXX-XXXX` when the digits allow. Anything that does not parse cleanly is passed through as the cleaned original rather than dropped.

**What if a search returns nothing?**
The run logs whether it was an empty result set or a block, writes a summary and charges nothing.

### Use it from Claude, ChatGPT and any MCP agent

Hosted MCP endpoint, no install, OAuth on first connect:

```
https://mcp.apify.com/?tools=themineworks/yellowpages-us
```

Claude Desktop / Cursor config with token auth:

```json
{
  "mcpServers": {
    "yellowpages": {
      "url": "https://mcp.apify.com/?tools=themineworks/yellowpages-us",
      "headers": { "Authorization": "Bearer YOUR_APIFY_TOKEN" }
    }
  }
}
```

Or call it from code with the Apify client:

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

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });

const run = await client.actor('themineworks/yellowpages-us').call({
  "searchTerm": "plumbers",
  "location": "Austin, TX",
  "maxResults": 100
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Related actors

- **[Google Maps Search Scraper](https://apify.com/themineworks/google-maps-search-scraper)**: the same local businesses from Google, with coordinates and ratings.
- **[Maps Leads](https://apify.com/themineworks/maps-leads)**: local business leads with contact enrichment.
- **[Website Contact Finder](https://apify.com/themineworks/website-contact-finder)**: emails from the websites this actor surfaces.
- **[Email Verifier & Validator](https://apify.com/themineworks/email-verifier-validator)**: clean the list before you send.

***

**Disclaimer:** This actor is an independent tool and is not affiliated with, endorsed by, or sponsored by Thryv, Inc. or YP LLC. Yellow Pages and YP are trademarks of their respective owners. Use scraped business data in line with CCPA, CAN-SPAM, TCPA, and your local laws.

Found a bug or want a field added? Open an issue from the actor's Apify Console page or reach out through the [The Mine Works profile](https://apify.com/themineworks).

### Related guides

- [How to Scrape Yellow Pages US Business Listings in Python (Phone, Address, Website)](https://themineworks.com/blog/yellowpages-scraper-us-business-leads-api)

*Last verified: 2026-08*

# Actor input Schema

## `searchTerm` (type: `string`):

What kind of business to find (e.g. "plumbers", "dentists", "coffee shops", "law firms"). Maps to the YellowPages keyword search.

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

US city and 2-letter state to search in, formatted "City, ST" (e.g. "Austin, TX", "Chicago, IL", "Miami, FL"). You can also use a 5-digit ZIP code.

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

Maximum number of business listings to return. Pagination continues across result pages until this many unique businesses are collected or YellowPages runs out of results.

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

YellowPages.com blocks datacenter traffic; US residential proxies are required for reliable access. Leave the prefilled value as-is unless you have a reason to change it.

## Actor input object example

```json
{
  "searchTerm": "plumbers",
  "location": "Austin, TX",
  "maxResults": 25,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

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

No description

# 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 = {
    "searchTerm": "plumbers",
    "location": "Austin, TX",
    "maxResults": 25,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "US"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("themineworks/yellowpages-us").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 = {
    "searchTerm": "plumbers",
    "location": "Austin, TX",
    "maxResults": 25,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "US",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("themineworks/yellowpages-us").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 '{
  "searchTerm": "plumbers",
  "location": "Austin, TX",
  "maxResults": 25,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}' |
apify call themineworks/yellowpages-us --silent --output-dataset

```

## MCP server setup

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

```

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/S9Esx8CKs7faofluL/builds/hN7HAPW0uDL3CYEcK/openapi.json