# Yellow Pages API (`visita/yellow-pages-api`) Actor

The Yellow Pages API is a fast and reliable tool for extracting public business data from YP.com. Simply provide a search term (like "plumbers" or "restaurants") and a location (like "New York, NY" or "90210"), and the Actor will scrape and structure the business listings for you.

- **URL**: https://apify.com/visita/yellow-pages-api.md
- **Developed by:** [Visita Intelligence](https://apify.com/visita) (community)
- **Categories:** Lead generation
- **Security:** Limited permissions
- **Stats:** 14 total users, 0 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 scraped business items

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?

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 API

The **Yellowpages API** is a fast and reliable interface for extracting public business data from **[YP.com](https://www.yellowpages.com/)**. Simply provide a search term (like "plumbers" or "restaurants") and a location, and this API will return structured business listings in JSON, CSV, or Excel format.

This tool serves as a powerful, unofficial **Yellow Pages API**, allowing you to integrate business data directly into your applications, databases, or lead generation pipelines without needing complex contracts or official access tokens.

### What can the Yellowpages API do?

- **Retrieve Business Details:** Programmatically access essential data points like **business name**, **phone number**, **full address**, and **website**.
- **Get Rich Operational Data:** Fetch details such as **business hours**, accepted **payment methods**, "Years in Business," and **social media links**.
- **Analyze Reputation:** Access **star ratings**, total **review counts**, and business **categories**.
- **Extract Media & Assets:** Get URLs for **gallery images**, business **logos**, and "General Info" descriptions.
- **Cloud Integration:** Built on the Apify platform, this API supports **scheduling**, **webhooks**, and integration with other tools (Make, Zapier, etc.) via the standard Apify [API Client](https://docs.apify.com/api/v2).

### What data endpoints are available?

The API returns the following data structure for every business listing found:

| Field | Description |
| :--- | :--- |
| `crawl_url` | The source URL of the listing. |
| `business_name` | The name of the business. |
| `phone_number` | The primary phone number. |
| `full_address` | The complete street address, city, state, and ZIP. |
| `website_url` | The business's website. |
| `rating` | The average star rating (e.g., "5"). |
| `review_count` | The total number of reviews. |
| `categories` | A list of all business categories. |
| `business_hours` | Formatted hours (e.g., "Mon - Fri: 9:00 am - 5:00 pm"). |
| `email` | The business email (if publicly available). |
| `claimed_status` | "Claimed" or "Unclaimed". |
| `payment_methods`| List of accepted payment methods. |
| `social_links` | List of links to social media profiles. |
| `general_info` | The "General Info" description text. |

***

### How to use the Yellowpages API

1. **Configure Inputs:** In the [Apify Console](https://console.apify.com/), set your **Search Terms** (e.g., `Architects`) and **Locations** (e.g., `New York, NY`).
2. **Set Limits:** Define the **Total Businesses** you want to retrieve (e.g., `50`).
3. **Call the API:** Click **Start** (or call the API endpoint programmatically).
4. **Get Data:** Retrieve your results in JSON, CSV, or Excel from the **Storage** tab / API response.

***

### Pricing (Pay-Per-Event)

This API uses the **Pay Per Event (PPE)** model, ensuring you only pay for the data you successfully retrieve.

| Event | Price | Description |
| :--- | :--- | :--- |
| **API Start** (`apify-actor-start`) | $0.00005 | Charged once per run initialization. |
| **Business Record** (`scraped-business-item`) | $0.007 | Charged for each unique business profile successfully extracted. |

**Volume Discounts:**

- **Bronze plan:** $0.00633 / record
- **Silver plan:** $0.00567 / record
- **Gold plan:** $0.005 / record

The API respects the **Max cost per run** limit you set, ensuring you never go over budget.

***

### JSON Response Example

The API returns a clean JSON object for each business:

```json
[{
  "crawl_url": "[https://www.yellowpages.com/new-york-ny/mip/jbj-concept-523768808](https://www.yellowpages.com/new-york-ny/mip/jbj-concept-523768808)",
  "business_name": "JBJ Concept",
  "phone_number": "(646) 221-9138",
  "full_address": "313 E 61st St, New York, NY 10065",
  "website_url": "[http://www.jbjconcept.com](http://www.jbjconcept.com)",
  "rating": "5",
  "review_count": "12",
  "categories": [
    "Architects & Builders Services",
    "Architectural Designers"
  ],
  "general_info": "A multitalented interior designer...",
  "logo_url": "[https://i3.ypcdn.com/blob/](https://i3.ypcdn.com/blob/)...",
  "payment_methods": ["discover", "master card", "visa", "amex"],
  "neighborhoods": ["Upper East Side", "Upper Manhattan"],
  "social_links": ["[https://facebook.com/](https://facebook.com/)..."],
  "email": "joseph.by@hotmail.com",
  "business_hours": "Mon - Thu: 10:00 am - 8:00 pm | Fri: 10:00 am - 3:00 pm...",
  "claimed_status": "Claimed",
  "years_in_business": "22 Years in Business"
}]
```

***

### Technical Notes & Support

- **Proxy Requirement:** YP.com is a US-based directory. This API requires **US Residential Proxies** to function correctly. The default configuration handles this automatically.
- **Support:** If you encounter issues or need specific fields added to the API response, please use the **Issues** tab.

### Legal & Compliance

This API is designed to scrape only public data. It does not extract private user data. However, users must respect local regulations regarding data usage (such as GDPR or CCPA). Please read our blog post on the [legality of web scraping](https://blog.apify.com/is-web-scraping-legal/) for more information.

```
```

# Actor input Schema

## `searchQueries` (type: `array`):

Enter business types, one per line (e.g., 'plumbers', 'restaurants', 'lawyers').

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

Enter locations, one per line (e.g., 'New York, NY', '90210', 'San Francisco, CA').

## `maxTotalBusinesses` (type: `integer`):

Controls the total number of unique business pages the Actor will scrape.

## `maxBusinessesPerSearchPage` (type: `integer`):

The maximum number of business links to pull from *each* search results page.

## `verboseLog` (type: `boolean`):

Enables detailed logging for debugging.

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

YellowPages.com requires a US-based proxy to work. Please use Residential Proxies set to the 'United States'.

## Actor input object example

```json
{
  "searchQueries": [
    "Plumbers"
  ],
  "locations": [
    "New York, NY"
  ],
  "maxTotalBusinesses": 1,
  "maxBusinessesPerSearchPage": 1,
  "verboseLog": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

## `searchResults` (type: `string`):

View the full dataset of scraped Yellow Pages businesses.

## `exportCsv` (type: `string`):

Direct download link for CSV format.

## `exportJson` (type: `string`):

Direct download link for JSON format.

# 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 = {
    "searchQueries": [
        "Plumbers"
    ],
    "locations": [
        "New York, NY"
    ],
    "maxTotalBusinesses": 1,
    "maxBusinessesPerSearchPage": 1,
    "verboseLog": true,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "US"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("visita/yellow-pages-api").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 = {
    "searchQueries": ["Plumbers"],
    "locations": ["New York, NY"],
    "maxTotalBusinesses": 1,
    "maxBusinessesPerSearchPage": 1,
    "verboseLog": True,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "US",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("visita/yellow-pages-api").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 '{
  "searchQueries": [
    "Plumbers"
  ],
  "locations": [
    "New York, NY"
  ],
  "maxTotalBusinesses": 1,
  "maxBusinessesPerSearchPage": 1,
  "verboseLog": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}' |
apify call visita/yellow-pages-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,visita/yellow-pages-api"
        }
    }
}
```

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/zWbB6DDVoidQuQ2Ev/builds/kLLKGSN5hWfr4uMW4/openapi.json
