# Yellow Pages Business Directory Scraper (`devilscrapes/yellow-pages-business-scraper`) Actor

Search Yellow Pages business listings by keyword and US city — name, phone, address, categories, rating, review count, and website for every result. We rotate fingerprints and proxies so blocks don't stop your dataset.

- **URL**: https://apify.com/devilscrapes/yellow-pages-business-scraper.md
- **Developed by:** [DevilScrapes](https://apify.com/devilscrapes) (community)
- **Categories:** Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.20 / 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.

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

<div align="center">
  <img src=".actor/icon.svg" width="160" alt="Devil Scrapes mark" />

## Yellow Pages Business Directory Scraper

**💰 $1.21 / 1 000 results**  ·  pay only for results  ·  no credit card to try

*The target blocks; we get back up.* 😈

Search Yellow Pages business listings by keyword and US city — name, phone, address, categories, rating, review count, and website for every result. We rotate fingerprints and proxies so blocks don't stop your dataset.

</div>

***

### 🎯 What this scrapes

yellowpages.com carries US business listings spanning name, phone, address, categories, ratings, and websites for local-service and retail businesses across every US city. This Actor searches its public results pages by keyword and city, writing one structured row per listing — no login, no scraping the individual business detail pages, just the search-results feed, paginated to your `maxResults` cap.

Give it a `searchTerm` (category or free-text keyword) and a `location` (`"City, ST"`) and it pages through results until it hits your `maxResults` cap, the site's own listing total, or the last page — whichever comes first.

### 🔥 What we handle for you

- 🛡️ **We rotate browser fingerprints** (curl-cffi impersonation — Chrome / Firefox / Safari) so the target sees real-browser traffic, not Python.
- 🔁 **We retry with exponential backoff** on `408 / 429 / 5xx` and honour `Retry-After` — up to 5 attempts per page.
- 🌐 **We rotate proxy sessions on every block** — fresh session, fresh exit IP, before the next attempt.
- 🧱 **We back off when the target rate-limits.** Partial successes surface clearly; we never silently return an empty dataset.
- 🧊 **We keep the dataset clean** — Pydantic-validated rows, ISO-8601 timestamps, stable field shapes.
- 💰 **You pay only for results that land.** No data → no charge (only the small `actor-start` warm-up fee).

### 💡 Use cases

- **Lead-gen list building** — pull every plumber, roofer, or dentist in a target city into a call/email list ready for outreach.
- **Local-market research** — compare business density and category mix across cities before opening a new location or launching an ad campaign.
- **Sales prospecting tools** — ingest directory data as a feed for a broader prospecting or CRM-enrichment pipeline.
- **Competitive scans** — see how many competitors of a given category operate in a city, and how they compare on ratings and review counts.

### ⚙️ How to use it

1. Click **Try for free** at the top of the page.
2. Enter a `searchTerm` (e.g. `"plumbers"`) and a `location` (e.g. `"Austin, TX"`).
3. Optionally raise or lower `maxResults` (default `300`, cap `3000`).
4. Click **Start**. Matched listings stream into the run's dataset as they're found.
5. Export from **Storage → Dataset** as JSON, CSV, or Excel — or fetch via the API.

### 📥 Input

| Field | Type | Required | Default | Notes |
|---|---|:--:|---|---|
| `searchTerm` | `string` | yes | — | Category or free-text keyword, e.g. `"plumbers"`. |
| `location` | `string` | yes | — | US city + state, `"City, ST"` shape, e.g. `"Austin, TX"`. |
| `maxResults` | `integer` | no | `300` | Cap on total rows emitted, 1-3000. |
| `proxyConfiguration` | `object` | no | `{"useApifyProxy": true}` | Apify Proxy config. |

#### Example input

```json
{
  "searchTerm": "plumbers",
  "location": "Austin, TX",
  "maxResults": 300,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

### 📤 Output

Every row is one business listing from a search-results page.

| Field | Type | Notes |
|---|---|---|
| `business_name` | `string` | Business name. |
| `phone` | `string \| null` | Primary phone number, verbatim. |
| `street_address` | `string \| null` | Street address; null when absent. |
| `city` | `string \| null` | City, parsed from the locality text. |
| `state` | `string \| null` | US state abbreviation. |
| `zip_code` | `string \| null` | ZIP code. |
| `categories` | `array` | Business categories, DOM order — empty array (never null) when absent. |
| `website` | `string \| null` | Website link as listed by Yellow Pages, verbatim — may be a tracked redirect, not necessarily the business's own domain. |
| `rating` | `number \| null` | Star rating, 1.0-5.0 in 0.5 steps; null when unrated. |
| `review_count` | `integer \| null` | Number of reviews; null when unrated. |
| `listing_url` | `string` | Absolute URL to the business's Yellow Pages listing page. |
| `search_term` | `string` | Echo of the run's `searchTerm` input. |
| `location_query` | `string` | Echo of the run's `location` input. |
| `scraped_at` | `string` | ISO-8601 UTC timestamp when this row was recorded. |

#### Example output

```json
{
  "business_name": "ARS / Rescue Rooter",
  "phone": "(512) 837-9500",
  "street_address": "1500 W Anderson Ln",
  "city": "Austin",
  "state": "TX",
  "zip_code": "78757",
  "categories": ["Plumbers", "Air Conditioning Contractors & Systems", "Heating Contractors & Specialties"],
  "website": "https://www.ars.com/austin",
  "rating": 4.5,
  "review_count": 128,
  "listing_url": "https://www.yellowpages.com/austin-tx/mip/ars-rescue-rooter-473194899",
  "search_term": "plumbers",
  "location_query": "Austin, TX",
  "scraped_at": "2026-07-30T12:00:00Z"
}
```

### 💰 Pricing

Pay-Per-Event — you pay only when these events fire:

| Event | USD | What it is |
|---|---:|---|
| `actor-start` | $0.01 | One-off warm-up charge per run |
| `result` | $0.0012 | Per business listing row written to the dataset |

Example: 1 000 rows ≈ **$1.21** (1 000 × $0.0012 + one $0.01 start charge). No subscription, no minimum, no card to start — Apify gives every new account $5 of free credit.

### 🚧 Limitations

v1 covers yellowpages.com US search-results pages only — not individual business detail/profile pages, not Canada's yellowpages.ca or any other country's directory, and not geocoding/validation of the `location` input against a real city/state gazetteer (format-shape validation only). The `website` field is captured verbatim with no redirect-following. Each run is a full fresh scrape; there is no cross-run deduplication or incremental/resume crawling.

### ❓ FAQ

**Does this scrape individual business detail pages?**

Not in v1. This Actor scrapes yellowpages.com's search-results pages only (name, phone, address, categories, rating, review count, and website per listing); detail-page enrichment (hours, full photo set, additional phones) is a v2 candidate.

**Is the website field the business's own domain?**

Not always. It's captured verbatim as listed by Yellow Pages — sometimes a tracked redirect or a micro-site rather than the business's own domain. We don't silently "correct" it.

**Do I need a Yellow Pages account?**

No. This Actor reads yellowpages.com's public search-results pages directly — no login required.

**What happens if a run gets blocked mid-way?**

We rotate browser fingerprints and proxy sessions on every block and retry with backoff. If the target still stops us, the run reports exactly how many rows it collected before stopping — never a silent empty dataset with a green status.

### 💬 Your feedback

Spotted a bug, hit a weird edge case, or need a new field? Open an
issue on the Actor's **Issues** tab on Apify Console — we ship
fixes weekly and we read every report.

***

<div align="center">

Built by **[Devil Scrapes](https://apify.com/DevilScrapes)** 😈 — a small fleet of
opinionated public-data Actors. Honest pricing, real engineering, zero fine print.

</div>

# Actor input Schema

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

Category or free-text keyword to search, e.g. "plumbers" or "italian restaurants". Passed as yellowpages.com's search\_terms parameter.

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

US city + state to search, in "City, ST" shape, e.g. "Austin, TX". Passed as yellowpages.com's geo\_location\_terms parameter. Not geocoded — must contain a comma.

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

Cap on total rows emitted for the run. Default covers 10 pages (30 rows/page); the run stops earlier if the site's own listing total or the last page is reached first.

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

Apify Proxy configuration. Group is intentionally left unset (AUTO) pending a cloud-recon smoke test; we'll switch the default to RESIDENTIAL if that check shows it's needed.

## Actor input object example

```json
{
  "searchTerm": "plumbers",
  "location": "Austin, TX",
  "maxResults": 300,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `datasetItems` (type: `string`):

All dataset items as JSON.

## `datasetItemsCsv` (type: `string`):

Same data exported to CSV.

## `datasetView` (type: `string`):

Open the run dataset in the Console.

# 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": 300,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("devilscrapes/yellow-pages-business-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 = {
    "searchTerm": "plumbers",
    "location": "Austin, TX",
    "maxResults": 300,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("devilscrapes/yellow-pages-business-scraper").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 '{
  "searchTerm": "plumbers",
  "location": "Austin, TX",
  "maxResults": 300,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call devilscrapes/yellow-pages-business-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=devilscrapes/yellow-pages-business-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/na46ItPDVhJQv007T/builds/GYtQswyCY2hfOFIOX/openapi.json