# YellowPages Business Scraper (`axlymxp/yellowpages-business-scraper`) Actor

Scrape US business listings from YellowPages — name, phone, email, website, full address, GPS, categories, opening hours, ratings and reviews — as structured JSON for lead generation and local market research. Search by keyword and city, or around a GPS point. Pay only for the results you get.

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

## Pricing

from $1.50 / 1,000 dataset items

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?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## YellowPages Business Scraper

**Turn any US city and industry into a clean, ready-to-use list of local businesses** — complete with phone numbers, email addresses, real websites, GPS coordinates, opening hours, categories and customer ratings.

Give it a keyword (`plumber`, `italian restaurant`, `dentist`) and a location (`Austin, TX`, `90210`), and it returns structured JSON you can drop straight into a CRM, a spreadsheet, or your own application.

***

### Who uses this

| You are | You use it to |
| ------- | ------------- |
| **Lead-generation agency** | Build targeted prospect lists — phone, email and website for every business in a city and vertical. |
| **Sales team** | Fill your pipeline with local businesses that match your ICP, filtered by category, rating or "open now". |
| **Local SEO / marketing agency** | Audit a market: who is listed, who has claimed their profile, who has no website, who has poor ratings. |
| **Market researcher / analyst** | Measure category density, competitive saturation and business longevity across metros. |
| **PropTech / SaaS developer** | A stable JSON business directory endpoint you can schedule, webhook and integrate. |

***

### What you get — output fields

| Field | Type | Description |
| ----- | ---- | ----------- |
| `ypid` | string | YellowPages business ID (stable identifier). |
| `name` | string | Business name. |
| `phone` | string | Formatted phone number, e.g. `(512) 766-0970`. |
| `email` | string | Business email address.¹ |
| `website` | string | The merchant's **own** website (not a YellowPages link).¹ |
| `yellowPagesUrl` | string | Public YellowPages profile URL. |
| `address` | object | `street`, `city`, `state`, `zip` as separate fields. |
| `addressFormatted` | string | Full address on one line. |
| `latitude` / `longitude` | number | GPS coordinates for mapping and radius analysis. |
| `neighborhoods` | array | Neighborhood names.¹ |
| `primaryCategory` | string | Main category heading, e.g. `Plumbers`. |
| `categories` | array | Every category the business is listed under. |
| `rating` | number | Average star rating (0–5). |
| `ratingCount` | integer | Number of ratings.² |
| `reviewCount` | integer | Number of written reviews.¹ |
| `starBreakdown` | object | Ratings histogram keyed `"1"`–`"5"`.¹ |
| `isClaimed` | boolean | Whether the owner has claimed the listing — a strong lead-qualification signal. |
| `yearEstablished` | string | Year the business was founded. |
| `hoursText` | string | Opening hours as displayed text.¹ |
| `hours` | object | Machine-readable hours, e.g. `{"monday": "0900-1700"}`.¹ |
| `openNow` / `open24Hours` | boolean | Current open state and 24-hour flag. |
| `services` | array | Services offered.¹ |
| `amenities` | array | Advertised amenities. |
| `paymentMethods` | array | Accepted payment methods.¹ |
| `languagesSpoken` | string | Languages spoken at the business.¹ |
| `description` | string | Business description / general info. |
| `slogan` | string | Business tagline.¹ |
| `socialLinks` | array | Facebook, LinkedIn, X/Twitter and other profile URLs. |
| `photos` | array | Photo URLs. |
| `chainId` | string | Chain identifier when the business belongs to a retail brand. |
| `distanceMiles` | number | Distance from the searched location. |
| `hasCoupons` | boolean | Whether the listing currently offers a coupon or deal. |
| `reviewSnippets` | array | Short review excerpts included with every result. |
| `reviews` | array | Full reviews — author, rating, body, date.³ |
| `searchTerm` / `searchLocation` | string | The query that produced the row. |
| `scrapedAt` | string | UTC extraction timestamp (ISO 8601). |

¹ Requires **Include full business details** (on by default).
² `ratingCount` can exceed the number of written reviews, because YellowPages includes aggregate ratings from partner sources.
³ Requires **Include customer reviews**.

***

### High-value use cases

**1. Build a cold-outreach list for a service vertical.**
Search `HVAC contractor` across 20 metros with details on. You get phone, email and website for each business, plus `isClaimed` so you can prioritise owners who already engage with their listings.

**2. Find businesses with no web presence.**
Filter the output for rows where `website` is empty — an instantly qualified prospect list for web-design and digital-marketing agencies.

**3. Reputation-based targeting.**
Sort by `rating` and filter on `ratingCount` and `starBreakdown` to find businesses with poor or thin review profiles — the core prospect list for reputation-management services.

**4. Local market analysis.**
Pull every `restaurant` in a metro with GPS coordinates, then map category density, clustering and white space for site selection.

**5. Keep a CRM fresh.**
Schedule a monthly run for your territories and diff on `ypid` to catch new businesses, closures, phone changes and new websites.

***

### Input parameters

| Parameter | Type | Default | Description |
| --------- | ---- | ------- | ----------- |
| `searchTerms` | array | `["plumber"]` | Keywords or categories. Each is searched in every location. |
| `locations` | array | `["Austin, TX"]` | US locations — `"City, ST"` or ZIP code. |
| `latitude` / `longitude` | number | — | Search around a GPS point instead of a named location. |
| `maxItems` | integer | `100` | Total result cap for the run. |
| `maxItemsPerQuery` | integer | `100` | Cap per search term × location combination. |
| `includeDetails` | boolean | `true` | Adds email, real website, full hours, services, payment methods, star breakdown. |
| `includeReviews` | boolean | `false` | Attaches full customer reviews to each business. |
| `maxReviewsPerBusiness` | integer | `10` | Used only when reviews are enabled. |
| `openNow` | boolean | `false` | Only businesses currently open. |
| `dealsOnly` | boolean | `false` | Only businesses offering a coupon or deal. |
| `sort` | enum | `relevance` | `relevance`, `distance`, `rating` or `name`. |
| `filters` | array | `[]` | Advanced raw facet values. |
| `proxyConfiguration` | object | off | Optional — not normally needed. |

***

### Example input

```json
{
  "searchTerms": ["plumber", "hvac contractor"],
  "locations": ["Austin, TX", "San Antonio, TX"],
  "includeDetails": true,
  "includeReviews": false,
  "maxItems": 500,
  "sort": "rating"
}
```

### Example output

```json
{
  "ypid": "10674347",
  "name": "Clarke Kent Plumbing",
  "phone": "(512) 766-0970",
  "email": "admin@clarkekentplumbing.com",
  "website": "http://www.clarkekentplumbing.com",
  "yellowPagesUrl": "https://www.yellowpages.com/austin-tx/mip/clarke-kent-plumbing-10674347",
  "address": {
    "street": "1408 W Ben White Blvd",
    "city": "Austin",
    "state": "TX",
    "zip": "78704"
  },
  "addressFormatted": "1408 W Ben White Blvd, Austin, TX 78704",
  "latitude": 30.228342,
  "longitude": -97.78136,
  "neighborhoods": ["South Lamar"],
  "primaryCategory": "Plumbers",
  "categories": ["Plumbers", "Plumbing-Drain & Sewer Cleaning"],
  "rating": 2.87,
  "ratingCount": 15,
  "starBreakdown": { "1": 8, "2": 0, "3": 0, "4": 0, "5": 7 },
  "isClaimed": true,
  "yearEstablished": "1986",
  "hoursText": "Mon - Fri 9:00 am - 5:00 pm, Sat - Sun Closed",
  "hours": { "monday": "0900-1700", "tuesday": "0900-1700" },
  "openNow": false,
  "paymentMethods": ["CHECK", "AMEX", "DISCOVER", "VISA", "CASH", "MASTER CARD"],
  "languagesSpoken": "Spanish",
  "slogan": "Smart Service * Trusted Reputation",
  "socialLinks": ["https://www.linkedin.com/company/clarke-kent-plumbing"],
  "searchTerm": "plumber",
  "searchLocation": "Austin, TX",
  "scrapedAt": "2026-09-18T08:11:13Z"
}
```

***

### Scheduling, webhooks and integrations

- **Schedule** runs (daily, weekly, monthly) from the Apify Console to keep a territory list current.
- **Webhooks** fire on run completion so your backend can ingest results immediately.
- **Export** to JSON, CSV, Excel, XML or JSONL — or pull from the Dataset API.
- **Integrations**: Google Sheets, Zapier, Make, Slack, Airbyte, Amazon S3 and Google Drive.

```bash
curl "https://api.apify.com/v2/datasets/<DATASET_ID>/items?format=csv&clean=true"
```

***

### Use it from an AI assistant (MCP)

Every Apify Actor is callable over the **Model Context Protocol**, so assistants such as Claude, ChatGPT or Cursor can run this scraper as a tool.

```json
{
  "mcpServers": {
    "apify": {
      "command": "npx",
      "args": ["-y", "@apify/actors-mcp-server", "--actors", "axlymxp/yellowpages-business-scraper"],
      "env": { "APIFY_TOKEN": "<YOUR_APIFY_TOKEN>" }
    }
  }
}
```

Then just ask: *"Find me 50 top-rated HVAC contractors in Phoenix with phone numbers and emails."*

***

### FAQ

**How many results can I get per run?**
There is no hard cap — set `maxItems` to whatever you need. Pagination is handled automatically, and progress is checkpointed so long runs survive interruptions and resume without duplicating rows.

**How fresh is the data?**
Every run fetches live data at request time. Nothing is served from a cache, and each row carries a `scrapedAt` timestamp.

**Why do some businesses have no email or website?**
Those fields only exist when the business has published them. Enable **Include full business details** to get the maximum coverage; rows without them simply return `null` rather than failing.

**Why is `ratingCount` higher than the number of reviews returned?**
YellowPages aggregates star ratings from partner sources but only hosts a subset as full written reviews. This is expected, not an error.

**Will it break when the website changes?**
This scraper reads a structured JSON data source rather than parsing HTML pages, which makes it substantially more stable than HTML-based scrapers. Runs that hit a transient error retry automatically with exponential backoff.

**What happens with an empty or invalid search?**
Invalid input (for example a bad sort value or a missing location) is rejected immediately with a clear message. A valid search that simply has no matches finishes cleanly with zero results.

**Is scraping this data legal?**
The actor collects only publicly available business information — the same data any visitor can see without logging in. No personal accounts, private data or logins are involved. You are responsible for using the output in line with applicable laws and regulations, including GDPR/CCPA where relevant.

**Can I get support?**
Yes — open an issue on the Actor's Issues tab and it will be addressed.

# Actor input Schema

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

Keywords or category names to search for, e.g. "plumber", "italian restaurant", "dentist". Each term is searched in every location below.

## `locations` (type: `array`):

US locations to search in — "City, ST" or a ZIP code (e.g. "Austin, TX", "90210"). Leave empty if you use latitude/longitude instead.

## `latitude` (type: `number`):

Search around a GPS point instead of a named location. Must be paired with longitude.

## `longitude` (type: `number`):

Search around a GPS point instead of a named location. Must be paired with latitude.

## `maxItems` (type: `integer`):

Stop the whole run after this many business records.

## `maxItemsPerQuery` (type: `integer`):

Cap the results collected for each individual term × location combination.

## `includeDetails` (type: `boolean`):

Fetch each business's profile to add the merchant's real website and email, machine-readable opening hours, star-rating breakdown, services, payment methods and neighborhoods. Adds one request per business.

## `includeReviews` (type: `boolean`):

Attach native YellowPages reviews (author, rating, full text, date) to each business. Note that YellowPages review volume is low — many businesses have none.

## `maxReviewsPerBusiness` (type: `integer`):

Only used when 'Include customer reviews' is enabled.

## `openNow` (type: `boolean`):

Restrict results to businesses currently open.

## `dealsOnly` (type: `boolean`):

Restrict results to listings that currently offer a coupon or deal.

## `sort` (type: `string`):

How results are ordered within each search.

## `filters` (type: `array`):

Raw YellowPages facet values, e.g. "coupon\_source:GRP". For advanced users; leave empty unless you know the facet names.

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

Optional. This actor uses an API that does not require a proxy, so you can normally leave this off.

## Actor input object example

```json
{
  "searchTerms": [
    "plumber"
  ],
  "locations": [
    "Austin, TX"
  ],
  "maxItems": 100,
  "maxItemsPerQuery": 100,
  "includeDetails": true,
  "includeReviews": false,
  "maxReviewsPerBusiness": 10,
  "openNow": false,
  "dealsOnly": false,
  "sort": "relevance",
  "filters": [],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `dataset` (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 = {
    "searchTerms": [
        "plumber"
    ],
    "locations": [
        "Austin, TX"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("axlymxp/yellowpages-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 = {
    "searchTerms": ["plumber"],
    "locations": ["Austin, TX"],
}

# Run the Actor and wait for it to finish
run = client.actor("axlymxp/yellowpages-business-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"
  ],
  "locations": [
    "Austin, TX"
  ]
}' |
apify call axlymxp/yellowpages-business-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,axlymxp/yellowpages-business-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/MtDiy5B7culurhGsY/builds/DIczUhCRe9xATkld0/openapi.json