# YellowPages US Scraper (`vp1337/yellowpages-scraper`) Actor

- **URL**: https://apify.com/vp1337/yellowpages-scraper.md
- **Developed by:** [Ville Petteri](https://apify.com/vp1337) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 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/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 — US Business Leads

Search [yellowpages.com](https://www.yellowpages.com) and get clean, structured
business leads: **name, phone, address, website, categories, ratings, years in
business** — one row per listing, ready for your CRM, spreadsheet, or agent
pipeline.

### Why this scraper

- **You only pay for results.** $2 per 1,000 listings. Failed requests cost
  nothing. Searches are paginated automatically until your `maxResults` is
  reached.
- **Built to stay working.** Yellow Pages blocks lazy scrapers; this one runs
  residential proxies with automatic session rotation and browser-consistent
  fingerprints. When the site changes, this actor gets fixed — issues are
  answered within a day.
- **Honest output.** Sponsored listings are flagged (`isAd`) instead of mixed
  invisibly into your leads. Fields that Yellow Pages doesn't provide come back
  as `null`, never as guesses.
- **Respects your budget.** If you set a maximum charge per run, the scraper
  stops exactly at what your budget pays for.
- **Agent-ready.** Clean JSON, one event per result — built to be called by AI
  agents and MCP tools, not just humans.

### Input

| Field | Example | Notes |
|---|---|---|
| `searchTerms` | `plumber` | What to search for |
| `location` | `Austin, TX` | City/state or ZIP |
| `maxResults` | `100` | Stop after this many listings |

```json
{
    "searchTerms": "roofing contractor",
    "location": "Phoenix, AZ",
    "maxResults": 100
}
```

### Output

One dataset item per business:

```json
{
    "name": "Butler Plumbing",
    "phone": "(512) 282-2265",
    "street": "9709 Swansons Ranch Rd",
    "locality": "Austin, TX 78748",
    "categories": ["Plumbers"],
    "website": "http://butlerplumbing.example.com",
    "ypUrl": "https://www.yellowpages.com/austin-tx/mip/butler-plumbing-7259871",
    "ypId": "7259871",
    "rating": 4.5,
    "ypRatingCount": 15,
    "yearsInBusiness": "75 Years",
    "isAd": false,
    "snippet": "Family-owned plumbing since 1949...",
    "searchTerms": "plumber",
    "location": "Austin, TX"
}
```

The Output tab includes a **"With phone numbers"** view — only the directly
contactable listings, ready to export.

### Common uses

- **Lead generation** — pull every plumber, dentist, or roofer in a metro with
  phone numbers and websites.
- **Market research** — category coverage, ratings, and years-in-business across
  cities.
- **Data enrichment** — match your records against Yellow Pages listings by name
  and location (`ypId` gives you a stable key).
- **AI agents** — call it as a tool; pay per result with no subscription.

### Pricing

| Event | Price |
|---|---|
| Per result | $0.002 ($2 per 1,000 listings) |
| Actor start | $0.005 |
| Empty search (zero listings found) | $0.002 |

No subscription. No charge for failed requests.

### Notes

- Some sponsored ("nationwide") listings genuinely carry no phone/address on
  Yellow Pages — those fields are `null` and the listing is flagged `isAd`.
- This actor scrapes publicly listed business-directory data only.

Found a problem or need a field added? **Open an issue — I read them.**

# Actor input Schema

## `searchTerms` (type: `string`):

What to search for, e.g. plumber, dentist, roofing

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

City/state or ZIP, e.g. 'Austin, TX' or '78701'

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

Stop after this many listings

## `debugHtml` (type: `boolean`):

Store raw page HTML in the key-value store (development only)

## `proxyGroups` (type: `array`):

Apify proxy groups. Yellow Pages blocks datacenter IPs — keep RESIDENTIAL unless you know what you're doing.

## Actor input object example

```json
{
  "searchTerms": "plumber",
  "location": "Austin, TX",
  "maxResults": 50,
  "debugHtml": false,
  "proxyGroups": [
    "RESIDENTIAL"
  ]
}
```

# Actor output Schema

## `listings` (type: `string`):

Scraped business listings as JSON (one item per listing)

# 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 = {
    "proxyGroups": [
        "RESIDENTIAL"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("vp1337/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 = { "proxyGroups": ["RESIDENTIAL"] }

# Run the Actor and wait for it to finish
run = client.actor("vp1337/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 '{
  "proxyGroups": [
    "RESIDENTIAL"
  ]
}' |
apify call vp1337/yellowpages-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vp1337/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/eULb0RkpNgoPGxhh7/builds/17bZQcFmv3MXrdOIp/openapi.json