# Yellow Pages Scraper - Most Comprehensive (`kaix/yellowpages-scraper`) Actor

🔥 ~$0.1/1K places 🔥 Look up Yellow Pages businesses by link or ID, or search them by term and location. Returns every field Yellow Pages has, with reviews and photos.

- **URL**: https://apify.com/kaix/yellowpages-scraper.md
- **Developed by:** [Kai](https://apify.com/kaix) (community)
- **Stats:** 1 total users, 1 monthly users, 79.9% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.08 / 1,000 places

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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

## Yellow Pages Scraper - Most Comprehensive

Get every field that Yellow Pages has for a business, or find businesses by
search term and location. Each business comes with its phones, emails, links,
address, coordinates, and hours. It also has its categories, services, brands,
payment methods, ratings by star, TripAdvisor data, and more. Add every photo
and video, and every review and star-only rating, in the same record.

It covers three countries: the United States (yellowpages.com), the United
Kingdom (yell.com), and Canada (yellowpages.ca). Pick one with the **Country**
option.

Look up one business or search a whole city. In local tests, a US search of 60
businesses with all their reviews took 12 seconds. 300 businesses took 25 to 28
seconds. Start with a Yellow Pages link, a listing ID, or a search term and a
location.

### Countries

Set **Country** to the Yellow Pages you want. Each is a different company, so
your links, IDs, and locations must match the country you pick.

- **United States** (`us`, the default): yellowpages.com. Covers the 50 states
  and Washington, DC. Links look like
  `https://www.yellowpages.com/austin-tx/mip/iii-forks-467675667`.
- **United Kingdom** (`uk`): yell.com. Links look like
  `https://www.yell.com/biz/the-himalaya-london-901780159/`. Yell returns up to
  about 20 reviews per business.
- **Canada** (`ca`): yellowpages.ca. Links look like
  `https://www.yellowpages.ca/bus/Ontario/Toronto/Bardi-s-Steak-House/156059.html`.
  pagesjaunes.ca links work too. A search needs a place name, not coordinates.
  Canada records have their own fields; see [Canada records](#canada-records).
  The Actor reads web pages for Canada, so it is slower. At the default 256 MB,
  150 businesses with all reviews took about 3 minutes. More memory gives more
  CPU, so the run is faster.

### What can you do with it?

- **Local lead lists.** Search a trade in a city, such as plumbers in Austin.
  Each business comes with its phones, emails, website, address, categories,
  hours, and rating.
- **Email and contact enrichment.** In a sample of 200 businesses, 117 had at
  least one email. 198 had a website or another link.
- **Market research.** Count the businesses of a category in a city or a ZIP
  code. Sort them by distance, rating, or name.
- **Competitor benchmarking.** Compare ratings, ratings by star, years in
  business, services, brands, and payment methods across nearby businesses.
- **Listing audits.** Compare the name, address, phones, hours, and categories on
  Yellow Pages with your own records.
- **Reputation monitoring.** Collect the reviews and ratings of your places on a
  schedule. Use the review `id` to skip reviews that you already have.
- **Advertiser research.** See which businesses pay for a listing, with their ad
  text, coupons, and years with Yellow Pages.

### What data does it extract?

| Data | When you get it |
|---|---|
| Business ID, listing ID, name, Yellow Pages link | Every business |
| Phone (formatted and as digits), address, city, state, ZIP code, coordinates, time zone | Every business that has them. In a sample of 200 businesses, all had a phone and 191 had coordinates. |
| Emails, extra phones, fax and toll-free numbers, website and other links | When Yellow Pages lists them. In the sample: emails 117 of 200, links 198 of 200, extra phones 80 of 200. |
| Categories with their codes and breadcrumbs | Every business |
| Opening hours as text and for each day, open-now flag | Every business that has hours. 183 of 200 had hours for each day. |
| Description, slogan, services, brands, amenities, accreditations, associations, languages, payment methods, year established | When the business lists them |
| Rating, precise rating, rating and review counts, ratings by star, rating attributes, newest review, review snippets | Every business that has ratings |
| TripAdvisor rating, review count, reviews, and photos | When Yellow Pages shows TripAdvisor data. 28 of 200 had it. |
| Claimed flag, paid listing flag, ad text, coupons, years with Yellow Pages | Every business. Ad and coupon fields only for businesses that have them. |
| Features: an open set of attributes, such as ownership, free estimates, and services | When Yellow Pages has them |
| Search data: distance from the search center, listing type, and the whole search result | Businesses that come from a search |
| Reviews: ID, rating, text, dates, source, rating attribute scores, reviewer details, images | When `includeReviews` is on |
| Photos and videos: links, sizes, dates, uploader, covers, logos, and thumbnails | Every business. All of them when `includeMedia` is on, which is the default. |

Yellow Pages does not have every field for every business. A field that Yellow
Pages does not send is not in the record. Some fields are empty text or `[]`.

### Quick start

1. Pick a **Country** (US, UK, or Canada). Enter a Yellow Pages link or a listing ID in
   **Listing links or IDs**, or a **Search term** and a **Location** to search.
2. Turn on **Include reviews** if you want reviews, and set **Max reviews per
   business**. Use `0` to get all reviews.
3. Click **Start**. Download the results as JSON, CSV, Excel, or HTML.

The same input as JSON:

```json
{
  "businesses": ["https://www.yellowpages.com/austin-tx/mip/iii-forks-467675667"],
  "includeReviews": true,
  "maxReviewsPerBusiness": 20
}
```

### Examples by use case

**One business with its profile and photos.** Photos and videos are on by
default:

```json
{
  "businesses": ["467675667"]
}
```

**A profile without the full gallery.** This skips the separate photo and video
request:

```json
{
  "businesses": ["467675667"],
  "includeMedia": false
}
```

**A lead list.** The 200 best-rated plumbers in Austin:

```json
{
  "searchTerm": "plumbers",
  "location": "Austin, TX",
  "searchSort": "average_rating",
  "maxSearchResults": 200
}
```

**Businesses in a ZIP code:**

```json
{
  "searchTerm": "roofing contractors",
  "location": "30301",
  "maxSearchResults": 100
}
```

**Competitors near a site.** Coffee shops around a point, nearest first:

```json
{
  "searchTerm": "coffee",
  "latitude": 40.7128,
  "longitude": -74.006,
  "searchSort": "distance",
  "maxSearchResults": 50
}
```

**Businesses and their reviews in one run.** 20 pizza places with up to 10
reviews each:

```json
{
  "searchTerm": "pizza",
  "location": "Chicago, IL",
  "maxSearchResults": 20,
  "includeReviews": true,
  "maxReviewsPerBusiness": 10
}
```

**Every review of a place:**

```json
{
  "businesses": ["https://www.yellowpages.com/new-york-ny/mip/nello-4654897"],
  "includeReviews": true,
  "maxReviewsPerBusiness": 0
}
```

**A paid listing in one category.** Keep the `lid` part of the link:

```json
{
  "businesses": [
    "https://www.yellowpages.com/austin-tx/mip/ars-rescue-rooter-473194899?lid=1002194107214"
  ]
}
```

**A search and known businesses in one run:**

```json
{
  "searchTerm": "plumbers",
  "location": "Austin, TX",
  "maxSearchResults": 20,
  "businesses": ["467675667", "4654897"]
}
```

### Choose the businesses

Use one or both ways in the same run. Direct lookup reads the businesses that you
list. Search finds businesses for you.

| What you have | Use | Required input |
|---|---|---|
| A Yellow Pages link or a listing ID | Direct lookup | `businesses` |
| A search term and a city, ZIP code, or address | Search by location | `searchTerm` and `location` |
| A search term and a point on a map | Search by coordinates | `searchTerm`, `latitude`, and `longitude` |

When you set both, the dataset has the search results first, in search order.
The businesses from your list follow, in your order. A listed business that the
search already found is saved once.

#### Look up businesses

Put one or more entries in `businesses`. You can mix links and IDs in one run.

- **Link.** A business page link, such as
  `https://www.yellowpages.com/austin-tx/mip/iii-forks-467675667`. These forms
  work too:
  - The business profile pages, with `/bpp/` or `/bp/` in place of `/mip/`.
  - `m.yp.com` links.
  - A link without `https://`.
  - A link with `?lid=`. Keep it. It picks the category listing of a paid
    business. See "What is `lid`?" below.
- **Listing ID.** The number at the end of the link, such as `467675667`. Each
  record has it in the `ypid` field.

The Actor reads the businesses in your order, so the dataset keeps that order. A
repeated business is read again and saved again. A business that fails does not
stop the others. A listing ID that does not exist shows `does not exist on
Yellow Pages` in the log. Some entries are not a listing link or ID, such as a
search page link. They stop the run at the start with `Not a Yellow Pages
listing link or ID`.

#### Search for businesses

- **What.** `searchTerm` is required for a search. Use a trade, a category, or a
  business name, such as `plumbers`, `pizza`, or `dentists`.
- **Where.** Set `location` to a US city and state, a ZIP code, or an address. Or
  set `latitude` and `longitude` together. If you set both, the Actor uses
  `location`. A location that Yellow Pages cannot find stops the run with
  `Yellow Pages cannot find the location`.
- **US only.** Yellow Pages covers the 50 states and Washington, DC. A place
  outside the US can match a US town with the same name, so check the log line
  `Yellow Pages searched near ...` before a large run.
- **Canada.** Set `location` to a city, a city and province, or a postal code,
  such as `Toronto, ON` or `M5J 1S8`. Coordinates stop the run, because
  yellowpages.ca reads them as the whole province. A place that yellowpages.ca
  does not know gives an empty dataset. A city search can include paid listings
  from far away: a Toronto search had one 503 km away.
- **How many.** `maxSearchResults` is 50 by default. Yellow Pages serves about
  3,000 results for one search, so the maximum is 3,000.
- **Order.** `searchSort` is `relevance` (best match), `distance`,
  `average_rating`, or `name`.

The Actor saves each business of a search once. A search can count more
matches than it serves. For example, Yellow Pages counted 24,454 restaurants in
New York but served about 3,000. To get more businesses, split the area into
ZIP codes or use more specific terms. A search with no matches ends as succeeded
with an empty dataset, and the log shows `No businesses to collect`.

### Add reviews and media

| Add to each business | Setting | Default |
|---|---|---|
| Every photo and video, with covers, logos, and thumbnails | `includeMedia` | On |
| Reviews and star-only ratings | `includeReviews`, with `maxReviewsPerBusiness` (`0` for all) | Off, 20 |

Reviews are a list in the `businessReviews` field of each business.
`businessReviewsTotal` is the number of reviews that Yellow Pages serves for the
business. The record also has the Yellow Pages fields `reviews` (the newest
review), `ratings` (up to 5 ratings), and `reviewSnippets`. These come
with every business, also when `includeReviews` is off.

With `includeMedia` on, `media` holds every photo and video. With it off,
`media` holds the part of the gallery that the business details carry. In a
sample of 200 businesses, the full gallery had more items for 35 of them.

### Input reference

Give `businesses`, or a `searchTerm` with a `location` or a coordinate pair, or
both.

| Field | Type | Default | Description |
|---|---|---|---|
| `country` | string | `us` | Which Yellow Pages: `us` (yellowpages.com), `uk` (yell.com), or `ca` (yellowpages.ca). Links, IDs, and locations must match it. |
| `businesses` | string\[] | `[]` | Listing links or listing IDs for the chosen country. Repeated entries stay in order and are saved separately. |
| `searchTerm` | string | none | What to search for, such as `plumbers`, `pizza`, or a business name. A search also needs a location or a coordinate pair. |
| `location` | string | none | A city, state, ZIP/postcode, or address in the chosen country, such as `Austin, TX`, `10001`, `Leeds`, `WC2N`, or `Toronto, ON`. |
| `latitude` | number | none | From -90 to 90. Needs `longitude`. Not for Canada. |
| `longitude` | number | none | From -180 to 180. Needs `latitude`. Not for Canada. |
| `searchSort` | string | `relevance` | `relevance`, `distance`, `average_rating`, or `name`. United States and Canada. |
| `maxSearchResults` | integer | `50` | Maximum businesses from a search, from 1 to 3,000 (US and Canada) or a few hundred (UK). |
| `includeMedia` | boolean | `true` | Add every photo and video, with the cover, logo, and thumbnail images. |
| `includeReviews` | boolean | `false` | Add the reviews and star-only ratings of each business in `businessReviews`. |
| `maxReviewsPerBusiness` | integer | `20` | Maximum reviews for each business. `0` collects all reviews. |
| `proxyConfiguration` | object | Apify Proxy enabled | Optional connection settings managed by Apify. The default datacenter proxy works. |

These inputs stop the run at the start, with the message in quotes:

| Input | Message |
|---|---|
| No `businesses` and no `searchTerm` | `Provide businesses or a search term with a location` |
| `searchTerm` without a location or coordinates | `Search needs a location or latitude and longitude` |
| `location` or coordinates without `searchTerm` | `Search needs a search term` |
| Only one of `latitude` and `longitude` | `latitude and longitude must both be provided or both omitted` |
| Coordinates with `country` `ca` | `Canada search needs a location` |
| An entry in `businesses` that is not a listing link or ID | `Not a Yellow Pages listing link or ID` |

Unknown input fields are ignored. A value with the wrong type, such as a text
`maxSearchResults`, fails before the run starts.

<details>
<summary>Complete input examples</summary>

These valid inputs show how the fields fit together.

A lookup with reviews and media:

```json
{
  "businesses": [
    "https://www.yellowpages.com/austin-tx/mip/iii-forks-467675667",
    "4654897"
  ],
  "includeMedia": true,
  "includeReviews": true,
  "maxReviewsPerBusiness": 50,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

A search with every search field:

```json
{
  "searchTerm": "dentists",
  "location": "Austin, TX",
  "searchSort": "distance",
  "maxSearchResults": 25,
  "includeMedia": false,
  "includeReviews": true,
  "maxReviewsPerBusiness": 5
}
```

</details>

### Output

Each item in the dataset is one business. The **Overview** table shows the name,
listing ID, phone, emails, website, and address. It also shows the coordinates,
categories, rating, rating count, year established, claimed flag, and the
Yellow Pages link.

The record keeps every field that Yellow Pages sends, with the field names in
camelCase. So `phone_number` becomes `phoneNumber`, and `1_star_count` becomes
`1StarCount`. Nested fields are converted too. When Yellow Pages adds a field,
the record has it without an Actor update.

The Actor adds these fields:

| Field | Content |
|---|---|
| `yellowPagesUrl` | The listing page on yellowpages.com. |
| `searchListing` | The whole search result, or `null` for a direct lookup. |
| `businessReviews` | Every review and star-only rating, when `includeReviews` is on. |
| `businessReviewsTotal` | The number of reviews that Yellow Pages serves for the business, when `includeReviews` is on. |
| `scrapedAt` | The UTC time at which the Actor read the business. |

#### Fields by topic

- **Identity.** Listing ID, category listing ID, name, other names, claimed flag,
  paid listing flag, year established, and years with Yellow Pages.
- **Contact.** Phone, extra phones, fax and toll-free numbers, emails, website,
  other links, and a custom link.
- **Location.** Address, city, state, ZIP code, coordinates, time zone,
  neighborhoods, and a location description.
- **Hours.** Hours as text and for each day, open-now and open-24-hours flags,
  and the time of the next change.
- **Classification.** The main category, all categories, display categories,
  category codes, and category breadcrumbs.
- **Business details.** Description, slogan, services, brands, amenities,
  accreditations, associations, languages, payment methods, price range, and
  extra information.
- **Features.** An open set of attributes, such as ownership, free estimates,
  services, and the TripAdvisor good-for categories.
- **Ratings.** Rating, precise rating, rating and review counts, ratings by star,
  rating attributes, the newest review, up to 5 ratings, review snippets, and
  TripAdvisor data.
- **Advertising.** Ad text and images, the sponsor block, tier, coupons, and the
  advertising start date.
- **Media.** Photos and videos, covers, logos, and thumbnails.
- **Search.** The whole search result, with the distance and the listing type.
- **Reviews.** Every review and star-only rating, when you ask for them.
- **Run.** The UTC time at which the Actor read the business.

#### Business example

This example is Texan Water from a search for plumbers in Austin, TX, with two
reviews. It is shortened. It shows 47 of the 136 fields of this business. Long
lists keep one or two items, and the rating in `ratings` shows 12 of its 37
fields. Square brackets mark values removed from the documentation.

<details>
<summary>Open the business JSON</summary>

```json
{
  "ypid": "541183367",
  "listingId": "1002182653008",
  "name": "Texan Water",
  "phoneNumber": "[phone]",
  "phone": "[phone]",
  "additionalEmails": [{"value": "[email]"}],
  "url": "https://texanwater.com",
  "address": "[street address]",
  "city": "Marble Falls",
  "state": "TX",
  "zip": "78654",
  "latitude": 30.579739,
  "longitude": -98.27547,
  "timezone": "America/Chicago",
  "headingText": "Pumps-Service & Repair",
  "allHeadings": ["Water Well Drilling & Pump Contractors", "Drilling & Boring Contractors"],
  "displayCategories": ["Pumps-Service & Repair", "Collection Agencies"],
  "categoryBreadcrumbs": [
    {
      "headingCode": "8009326",
      "headingText": "Plumbing Fixtures, Parts & Supplies",
      "displayText": "Plumbing Fixtures"
    }
  ],
  "generalInfo": "Texan Water provides Central Texas and the Hill Country with water well drilling, pump services and rain water storage systems",
  "brands": ["All major brands"],
  "paymentText": "CASH, MASTERCARD, VISA",
  "features": {
    "hasYpLocalAd": ["1"],
    "ownership": ["Locally Owned"],
    "services": [
      "Rain water collection systems",
      "Pump & storage system installation, testing & inspections"
    ],
    "userId": ["568308548"],
    "pflSourceId": ["AV8SVD-0BL-EMOgBdSj0"],
    "claimed": ["ypc"],
    "itlIds": ["10671652"],
    "freeEstimates": ["Yes"]
  },
  "opHours": "Mon - Sun 12:00 am - 11:59 pm",
  "hours": {
    "today": { "hours": [["Today", "12:00 am - 11:59 pm"]] },
    "details": [
      {
        "label": "Regular Hours",
        "text": "Mon - Sun 12:00 am - 11:59 pm",
        "hours": [["Mon - Sun", "12:00 am - 11:59 pm"]]
      }
    ]
  },
  "hoursXltd": {
    "default": {
      "standardHours": {
        "wednesday": "0000-2359",
        "monday": "0000-2359",
        "thursday": "0000-2359",
        "sunday": "0000-2359",
        "tuesday": "0000-2359",
        "friday": "0000-2359",
        "saturday": "0000-2359"
      }
    }
  },
  "openNow": true,
  "isClaimed": true,
  "isPaid": true,
  "seniorityYears": 8,
  "averageRating": 4.5,
  "preciseAverageRating": 4.5,
  "ratingCount": 8,
  "reviewCount": 8,
  "writtenRatingCount": 8,
  "1StarCount": 1,
  "2StarCount": 0,
  "3StarCount": 0,
  "4StarCount": 0,
  "5StarCount": 7,
  "ratings": [
    {
      "id": "7b05fc92-a02d-4ca0-9ddf-aa3887ca1af7",
      "value": 5,
      "source": "YP",
      "sourceId": "7b05fc92-a02d-4ca0-9ddf-aa3887ca1af7",
      "authorName": "[reviewer name]",
      "authorUserId": "[reviewer ID]",
      "createdAt": "2024-01-23 20:41:38 +0000",
      "updatedAt": "2026-06-19 18:16:54 +0000",
      "suppressed": false,
      "receivedOn": "2024-01-23 20:41:38 +0000",
      "body": "[review text]",
      "ypid": 541183367
    }
  ],
  "mipUrl": "/marble-falls-tx/mip/texan-water-541183367",
  "media": {
    "data": [
      {
        "extId": "541183367",
        "flagCount": 0,
        "fullImagePath": "http://i1.ypcdn.com/blob/0b6f6d545fa07ffaa0be7a16f38a45f2f5d12b77",
        "height": 2638,
        "id": "0b6f6d545fa07ffaa0be7a16f38a45f2f5d12b77",
        "imagePath": "/blob/0b6f6d545fa07ffaa0be7a16f38a45f2f5d12b77",
        "platform": "Web",
        "stateName": "public",
        "typeName": "ypid",
        "userId": "[uploader ID]",
        "width": 3983,
        "verified": 1,
        "blobMediaType": "image",
        "createdAt": "2017-10-12 21:34:01 +0000",
        "deleted": 0,
        "endDate": "2217-08-25 21:34:01 +0000",
        "primary": 0,
        "recurring": 0,
        "reviewedState": 0,
        "startDate": "2017-10-12 21:34:01 +0000",
        "state": 0,
        "typeId": 1,
        "updatedAt": "2021-12-01 23:16:53 +0000",
        "mediaCategory": "image",
        "userInfo": {
          "user": {
            "displayName": "[uploader name]",
            "firstName": "[uploader name]",
            "lastName": "[uploader name]",
            "createdAt": "2017-10-12 20:44:16 +0000",
            "id": "[uploader ID]",
            "verified": true
          },
          "reviews": { "count": 0 },
          "images": { "count": 3 },
          "currentUser": false
        },
        "user": "[uploader name]"
      }
    ],
    "totalCount": 3
  },
  "yellowPagesUrl": "https://www.yellowpages.com/marble-falls-tx/mip/texan-water-541183367",
  "searchListing": {
    "id": "541183367",
    "listingId": "1002182653008",
    "name": "Texan Water",
    "distance": 37.04,
    "listingType": "advertiser",
    "website": "http://www.yellowpages.com/marble-falls-tx/mip/texan-water-541183367",
    "averageRating": 4.5,
    "ratingCount": 8,
    "phone": "[phone]",
    "address": "[street address]",
    "city": "Marble Falls",
    "state": "TX",
    "zip": "78654",
    "openNow": true
  },
  "businessReviews": [
    {
      "authorName": "[reviewer name]",
      "authorUpdatedAt": "2026-06-19 18:16:54 +0000",
      "authorUserId": "[reviewer ID]",
      "body": "[review text]",
      "createdAt": "2024-01-23T20:41:38+00:00",
      "currentUserMarkedHelpful": null,
      "id": "7b05fc92-a02d-4ca0-9ddf-aa3887ca1af7",
      "images": [],
      "imageCount": 0,
      "isCommentingEnabled": false,
      "promoId": "",
      "rating": 5,
      "ratingAttributeScores": [
        { "id": "1007", "name": "Expertise", "score": 5 },
        { "id": "1017", "name": "Professionalism", "score": 5 },
        { "id": "1033", "name": "Promptness", "score": 5 }
      ],
      "ratingResponse": "",
      "reviewSource": "YP.com",
      "subject": "",
      "thumbsDown": null,
      "thumbsUp": null,
      "userInfo": {
        "user": {
          "avatarUrl": null,
          "displayName": "[reviewer name]",
          "firstName": "[reviewer name]",
          "lastName": "[reviewer name]",
          "createdAt": "2024-01-23 20:41:30 +0000",
          "id": "[reviewer ID]",
          "location": null,
          "verified": true,
          "zipCode": null,
          "badges": [],
          "totalHelpfulVotes": 0
        },
        "reviews": { "count": 1 },
        "images": { "count": 0 },
        "currentUser": false
      }
    }
  ],
  "businessReviewsTotal": 8,
  "scrapedAt": "2026-10-16T11:05:54.893Z"
}
```

</details>

#### Field groups

| Group | Root fields |
|---|---|
| Identity and status | `ypid`, `listingId`, `name`, `akas`, `isClaimed`, `isPaid`, `yearEstablished`, `year`, `seniorityYears`, `seniorityDate`, `vertical`, `source`, `chainId` |
| Contact | `phoneNumber`, `phone`, `allPhone`, `additionalPhones`, `email`, `additionalEmails`, `url`, `additionalUrls`, `customLink` |
| Location | `address`, `city`, `state`, `zip`, `zip4`, `latitude`, `longitude`, `timezone`, `neighborhoods`, `locationDescription`, `areaCode` |
| Hours | `opHours`, `hours`, `hoursXltd`, `openNow`, `open24Hours`, `moreHoursOfOperation`, `nextHourStateChange`, `nextHourStateChangeSeconds` |
| Classification | `headingText`, `allHeadings`, `displayCategories`, `translatedDisplayCategories`, `categoryBreadcrumbs`, `headingCode`, `allHeadingCodes`, `primaryHeadingCode`, `categoryType` |
| Business details | `generalInfo`, `description`, `slogan`, `services`, `brands`, `amenities`, `amenitiesFlags`, `accreditation`, `associations`, `languagesSpoken`, `paymentText`, `priceRange`, `additionalInfo` |
| Features | `features` |
| Ratings | `averageRating`, `preciseAverageRating`, `ratingCount`, `reviewCount`, `writtenRatingCount`, `1StarCount` to `5StarCount`, `ratingAttributes`, `ratingAttributeAverages`, `ratings`, `reviews`, `reviewSnippets`, `snippet`, `lastReviewDate`, `pageInsights`, `tripAdvisor` |
| Advertising | `adText`, `adImagePath`, `displayAd`, `graphic`, `sponsor`, `tier`, `tierFields`, `preferredBadge`, `advertisingStartDate`, `displayAdvertisingYears`, `coupons`, `couponFlag`, `dealFlag` |
| Media | `media`, `serpImageSha1`, `serpImageSha1Mult`, `lastImageDate` |
| Links | `yellowPagesUrl`, `mipUrl`, `spmipUrl`, `dkmipUrl` |
| Search | `searchListing` |
| Reviews | `businessReviews`, `businessReviewsTotal` |
| Run | `scrapedAt` |

The record has more fields than these groups list, such as `listingScore`,
`hotlistScore`, and `rhinoTimestamp`. The Actor keeps them too.

<details>
<summary>Field types</summary>

**Root fields**

The table lists the type of each root field in a sample of 200 businesses. A
field is left out when Yellow Pages does not send it.

| JSON type | Root fields |
|---|---|
| string | `ypid`, `listingId`, `name`, `phoneNumber`, `phone`, `allPhone`, `email`, `url`, `address`, `city`, `state`, `zip`, `zip4`, `timezone`, `areaCode`, `locationDescription`, `opHours`, `nextHourStateChange`, `headingText`, `headingCode`, `primaryHeadingCode`, `categoryType`, `vertical`, `generalInfo`, `slogan`, `services`, `languagesSpoken`, `paymentText`, `priceRange`, `yearEstablished`, `year`, `seniorityDate`, `lastReviewDate`, `advertisingStartDate`, `mipUrl`, `spmipUrl`, `dkmipUrl`, `ratingCountDk`, `ratingCountSp`, `averageRatingDk`, `averageRatingSp`, `couponFlag`, `dealFlag`, `scrapedAt` |
| string or `null` | `yellowPagesUrl` |
| number | `latitude`, `longitude`, `averageRating`, `preciseAverageRating`, `ratingCount`, `reviewCount`, `writtenRatingCount`, `1StarCount`, `2StarCount`, `3StarCount`, `4StarCount`, `5StarCount`, `seniorityYears`, `nextHourStateChangeSeconds`, `tier`, `businessReviewsTotal` |
| boolean | `isClaimed`, `isPaid`, `openNow`, `open24Hours`, `moreHoursOfOperation`, `mappable`, `preferredBadge`, `hasChildren` |
| string\[] | `akas`, `allHeadings`, `displayCategories`, `allHeadingCodes`, `neighborhoods`, `brands`, `amenities`, `accreditation`, `associations`, `adText` |
| object\[] | `additionalEmails`, `additionalUrls`, `categoryBreadcrumbs`, `translatedDisplayCategories`, `additionalInfo`, `ratingAttributes`, `ratingAttributeAverages`, `ratings`, `reviewSnippets`, `coupons`, `businessReviews` |
| object | `additionalPhones`, `customLink`, `description`, `features`, `hours`, `hoursXltd`, `media`, `pageInsights`, `reviews`, `snippet`, `sponsor`, `graphic`, `tierFields`, `tripAdvisor` |
| object or `null` | `searchListing` |

**Nested fields**

| Parent field | Child fields |
|---|---|
| `additionalEmails[]` | `value`: string; optional `label`: string |
| `additionalUrls[]` | `value`: string; optional `label`: string |
| `additionalPhones` | `extraPhone`, `extraFax`, `extraTollFree`: object\[]. Each item has a string `value` and an optional string `label`. |
| `customLink` | `label`, `link`: string |
| `additionalInfo[]` | `key`, `label`: string; `value`: string\[] |
| `hours` | `today`: object with `hours` as pairs of text; `details`: object\[] with `label`, `text`, and `hours` |
| `hoursXltd.default.standardHours` | `monday` to `sunday`: string, such as `0000-2359` |
| `categoryBreadcrumbs[]` | `headingCode`, `headingText`, `displayText`: string |
| `features` | Open object. Each value is an array, mostly of strings. `cta` holds objects. |
| `pageInsights` | `pageViews`, `ratings`, `checkins`, `followers`, `likes`: number |
| `tripAdvisor` | `rating`, `reviewCount`, `imageCount`, `reviewsUrl`, `imagesUrl`: string; `reviews`, `images`: object\[] |
| `media` | `data`: object\[]; `totalCount`: number; `covers`, `logos`, `thumbnails`: object\[] when Yellow Pages has them |
| `media.data[]` | `id`, `fullImagePath`, `imagePath`, `mediaCategory`, `createdAt`, `updatedAt`, `user`: string; `width`, `height`: number; optional `userInfo`: object; optional `caption`: string |
| `businessReviews[]` | `id`, `body`, `subject`, `createdAt`, `ratingResponse`: string; `authorName`, `reviewSource`: string or `null`; `rating`, `imageCount`: number; `ratingAttributeScores`, `images`: object\[]; `userInfo`: object |
| `businessReviews[].ratingAttributeScores[]` | `id`, `name`: string; `score`: number |

</details>

#### Field notes

- `ypid` is the business ID. Use it to remove repeated rows when you join the
  results of two runs. `listingId` is the listing of the business in one
  category. It was the same as `ypid` for 123 of 200 sampled businesses. A paid
  business has a listing for each category.
- `phoneNumber` is the formatted phone, such as `(512) 823-0000`. `phone` is the
  same number as digits.
- `email` is rare: 3 of 200 sampled businesses had it. Read `additionalEmails`
  too, which 115 of 200 had.
- `url` is the website of the business. `additionalUrls` holds the other links.
- `hoursXltd.default.standardHours` gives the hours for each day as 24-hour
  ranges, such as `0000-2359`. `opHours` gives the same hours as text.
- `openNow` and `nextHourStateChange` describe the time of the run.
- `averageRating` is the shown rating. `preciseAverageRating` is the exact
  average. `1StarCount` to `5StarCount` give the ratings for each star level.
- `ratingCount` can be higher than `businessReviewsTotal`. Some ratings exist
  only as counts. Yellow Pages does not serve them as reviews.
- `features` is an open set. In the sample, details had 89 different feature
  keys and search results had 138. The Actor copies the object whole.
- `searchListing` holds values that the details do not have, such as
  `distance` and `listingType`. `distance` is about the straight-line distance in
  miles from the search center. Some values differ from the details, such as
  `averageRating`. The Actor keeps both.
- `businessReviews[].body` is empty text for a star-only rating. In a sample of
  1,952 reviews, 14 had no text.
- `businessReviews[].reviewSource` is `YP.com`, `YPmobile`, or `null`.
- `businessReviews` keep the order of Yellow Pages. It is mostly newest first,
  but not always.
- `reviews` is the newest review that the details carry. It is not the full
  list.

#### Canada records

yellowpages.ca has no app API, so Canada records come from its website. They
have their own fields:

| Field | Content |
|---|---|
| `ypid`, `listingId` | `ca_` and the merchant ID, such as `ca_156059`; the merchant ID alone. |
| `name`, `yellowPagesUrl` | The business name and its page on yellowpages.ca. |
| `telephone`, `phones` | The main phone in international format; every phone with its label, such as `Primary`. |
| `website`, `bookingUrl` | The links that the page shows. |
| `address`, `geo` | Street, city, province, postal code, and country; latitude and longitude. |
| `openingHours` | The day, the opening time, and the closing time. |
| `description` | The full "Details & Description" text. |
| `rating`, `ratingCount`, `reviewCount` | The average rating, the number of ratings, and the number of written reviews. |
| `editorsPick` | `true` when the business has the Editor's Pick badge. |
| `paymentMethods`, `socialMedia` | The payment methods; the social links with their names. |
| `businessDetails` | The page's detail lists with their titles, such as Products and Services or Languages Spoken. |
| `linkGroups` | The Categories, Directories, and Landmarks links of the page. |
| `logo`, `image`, `media` | The logo, the main image, and the photo gallery with captions. |
| `searchListing` | The search card: the ad flag, headings, rating, phone, website, and best review. |
| `businessReviews` | Each written review: ID, rating, title, text, author, date, sub-ratings such as food and service, and helpful count. |

### FAQ

#### How many reviews can I get?

In the US there is no fixed limit. Set `maxReviewsPerBusiness` to `0` to get all
the reviews that Yellow Pages serves. In a sample of 200 businesses, 135 had no
reviews, and the most was 305. In the UK, Yell serves up to about 20 reviews per
business; `businessReviewsTotal` still reports the true count. In Canada,
yellowpages.ca serves every written review. Its star-only ratings count in
`ratingCount`, but the site does not serve them.

#### Why did I get fewer reviews than `ratingCount`?

`maxReviewsPerBusiness` is an upper limit, and it is 20 by default. Also, some
ratings exist only as counts. For example, ARS Rescue Rooter shows 113 ratings,
but Yellow Pages serves no reviews for it. The Yellow Pages app shows the same
empty list. `businessReviewsTotal` is the number that Yellow Pages serves.

#### Why do some reviews have no text?

They are star-only ratings. The Actor saves them with the reviews, so you get
every rating that Yellow Pages serves.

#### Why do some businesses have no address or coordinates?

Some businesses go to their customers, such as plumbers. They hide their
address on Yellow Pages. For them, `mappable` is `false` and `omitAddress` is
`Y` or `S`. In a search for plumbers in Austin, 11 of 60 businesses were like
this. 9 had no coordinates, and 2 had the placeholder `-10`, `-10`. 5 had an
approximate point in `assumedLat` and `assumedLon`. The Actor keeps these values
as Yellow Pages sends them.

#### How many businesses can one search return?

Yellow Pages serves about 3,000 results for one search, even when it counts
more. To get more, split the area into ZIP codes or cities, or use more specific
search terms. Then remove the repeats with the `ypid` field.

#### Can I search outside the United States?

Yes, in the United Kingdom and Canada. Set **Country** to `uk` to search
yell.com, or to `ca` to search yellowpages.ca. No other country is covered yet.

With **Country** `us`, Yellow Pages covers the 50 states and Washington, DC only.
It has no Canada, Puerto Rico, or other US territories. Some places outside the
US stop the run with `Yellow Pages cannot find the location`, such as
`Toronto, Canada`. Others match a US town with the same name: `Toronto, ON`
searched Toronto, Ohio. The log shows the place it searched. For Canada, set
**Country** to `ca`.

#### What is `lid`?

A paid business has one listing for each category, such as "Plumbers" and
"Water Heaters". `lid` in a link picks one of these listings. Keep it in the
link, because the category fields come from that listing. A search sends it for
you. A link without `lid` gets the listing that Yellow Pages chooses.

#### What happens when I misspell the search term?

In our tests, Yellow Pages still returned results for "resturants" and
"plumbr". It corrected "resturants" to "restaurants" and suggested "plumber" for
"plumbr". The log shows the suggestion, so check it before a large run.

#### How do I find the link or listing ID?

Open the business on yellowpages.com. Copy the link from the address bar. The
listing ID is the number at the end of the link, and every record has it in
`ypid`.

#### Can I search and look up businesses in one run?

Yes. Set `searchTerm` with a location and `businesses` in the same input. The
dataset has the search results first, then your list.

#### Why do I see the same business twice?

One search saves each business once. A business can show twice when your
`businesses` list has it twice. It can also show twice when you join two runs.
Remove the repeats with the `ypid` field.

#### What happens if a business fails?

The Actor saves the other businesses. The log shows `Failed to collect business`
or `does not exist on Yellow Pages` with the listing ID. The run still ends as
succeeded. The last log line gives the number of saved and failed businesses.

#### A feature or field that I need is missing. What can I do?

Tell us in the **Issues** tab. Describe what you need and give an example
business.

#### Where can I report a problem?

Open an issue in the **Issues** tab. Include the run ID and the input, so that
we can reproduce it.

### Similar Actors

- [Yelp Business Scraper](https://apify.com/kaix/yelp-business-scraper). Yelp
  businesses with ratings, hours, categories, attributes, photos, and reviews.
- [Yelp Reviews Scraper](https://apify.com/kaix/yelp-reviews-scraper). Yelp
  reviews and business details from business URLs, aliases, or business IDs.
- [Google Maps Scraper](https://apify.com/kaix/google-maps-places-scraper).
  Google Maps places with more than 120 fields, emails, and social profiles.
- [TripAdvisor Reviews](https://apify.com/kaix/tripadvisor-reviews-scraper).
  TripAdvisor reviews for restaurants, hotels, attractions, and cruises.
- [Trustpilot Reviews Scraper](https://apify.com/kaix/trustpilot-reviews-scraper).
  Trustpilot reviews and business profiles.

# Actor input Schema

## `country` (type: `string`):

Which Yellow Pages to scrape. The United States is yellowpages.com (Thryv). The United Kingdom is yell.com (Yell). Canada is yellowpages.ca (Yellow Pages Limited). Links, IDs and locations must match the country you pick.

## `businesses` (type: `array`):

Listing links or IDs for the country above. US: https://www.yellowpages.com/austin-tx/mip/iii-forks-467675667 or 467675667. UK: https://www.yell.com/biz/the-himalaya-london-901780159/ or 901780159. Canada: https://www.yellowpages.ca/bus/Ontario/Toronto/Bardi-s-Steak-House/156059.html or 156059. You can use this together with a search.

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

What to search for, e.g. 'plumbers', 'pizza' or a business name. A search also needs a location, or latitude and longitude. Canada needs a location.

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

A city, state, ZIP/postcode or address in the country above. US example: 'Austin, TX' or '10001'. UK example: 'Leeds' or 'WC2N'. Canada example: 'Toronto, ON' or 'M5J 1S8'. The US covers only the 50 states and Washington, DC; a place outside it can match a US town with the same name.

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

Search around a point instead of a location. Use it with Longitude. Not available for Canada: yellowpages.ca reads coordinates as the whole province.

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

Search around a point instead of a location. Use it with Latitude. Not available for Canada: yellowpages.ca reads coordinates as the whole province.

## `searchSort` (type: `string`):

The order of the search results. Applies to the United States and Canada.

## `maxSearchResults` (type: `integer`):

The most businesses to collect from the search. One search serves about 3,000 results in the US and Canada, and a few hundred in the UK.

## `includeMedia` (type: `boolean`):

Load every photo and video, with the cover, logo and thumbnail images. Without it, a business has the photos its details carry, which can be fewer.

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

Add the reviews and star-only ratings of each business in `businessReviews`.

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

The most reviews to collect for each business. Use 0 for all.

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

Proxy settings. The default Apify datacenter proxy works.

## Actor input object example

```json
{
  "country": "us",
  "businesses": [
    "https://www.yellowpages.com/austin-tx/mip/iii-forks-467675667"
  ],
  "searchSort": "relevance",
  "maxSearchResults": 50,
  "includeMedia": true,
  "includeReviews": false,
  "maxReviewsPerBusiness": 20,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `businesses` (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 = {
    "businesses": [
        "https://www.yellowpages.com/austin-tx/mip/iii-forks-467675667"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("kaix/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 = {
    "businesses": ["https://www.yellowpages.com/austin-tx/mip/iii-forks-467675667"],
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("kaix/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 '{
  "businesses": [
    "https://www.yellowpages.com/austin-tx/mip/iii-forks-467675667"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call kaix/yellowpages-scraper --silent --output-dataset

```

## MCP server setup

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