Yellow Pages US Scraper

Tell it what you want and where in the United States. "plumber" in "Austin, TX", "dentist" in "90210". You get one row per listing: business name, phone, street address, city, state, ZIP, website, the categories yellowpages.com files the business under, its star rating and review count, how many years it has been trading, and the link to the listing. No account to create, no browser involved.

Every search term is run against every location, so three trades across five cities is one run rather than fifteen.

Billing

$0.60 per 1,000 businesses, plus a $0.001 start fee per run (billed per gigabyte of run memory, so exactly that on the default 1 GB).

Same rate on every plan, free or paid. No volume tiers, no minimum spend, no subscription.

Businesses	Total cost
100	$0.061
1,000	$0.601
10,000	$6.001
100,000	$60.001

One business-scraped event per business row written to the dataset. Nothing else is metered per row. A business that turns up twice in one run, once as a sponsored placement and again as an ordinary result, or under two of your search terms, is returned once and charged once.

Free: the sample row an empty run returns, and every diagnostic row. A blocked target, a dead URL, a search that matched nothing. Those all carry "charged": false. A run that finds nothing costs the start fee and no more.

No price is attached to apify-default-dataset-item, so a diagnostic or a notice can't quietly bill you. Filter the dataset on "charged": true and the number of rows you get back is the number of events you were billed for.

Input

{
  "searchTerms": [
    "plumber",
    "hvac contractor"
  ],
  "locations": [
    "Austin, TX",
    "78704"
  ],
  "maxItems": 120,
  "includeAds": false
}

Field	What it does
searchTerms	What to look for, the way you would type it into the Yellow Pages search box: a trade, a category or a business name. Up to 20 per run.
locations	Where to look: a US "City, ST" such as Austin, TX, or a 5-digit ZIP such as 90210. Up to 20 per run. Every term is run against every location, and the run covers up to 30 searches in total.
maxItems	Total rows across all searches. The budget is shared evenly, so six searches and 300 rows gives you 50 of each. Results arrive 30 to a page. Default 30, hard ceiling 3,000.
includeAds	Off by default. Turn it on to also get the sponsored placements at the top of each page. They are real local businesses and arrive with "isAd": true.
searchUrls	Optional. Paste yellowpages.com search or category URLs directly instead of terms and locations. Anything that is not a yellowpages.com URL is skipped with a free diagnostic row.
proxyUrls	Leave empty. Fill it in only if you want the traffic to leave through proxy servers you already pay for, as http://user:pass@host:port.

Run it with empty input and you get one clearly labelled sample row, free, so you can see the output shape before you spend anything.

Output

One row per business. A real row from a real run:

{
  "ok": true,
  "charged": true,
  "recordType": "business",
  "name": "Clarke Kent Plumbing",
  "phone": "(512) 766-0970",
  "street": "1408 W Ben White Blvd",
  "city": "Austin",
  "state": "TX",
  "zip": "78704",
  "serviceArea": null,
  "website": "http://www.clarkekentplumbing.com/",
  "categories": [
    "Plumbers",
    "Plumbing-Drain & Sewer Cleaning"
  ],
  "rating": 2.87,
  "ratingIsApprox": false,
  "reviewCount": 15,
  "yearsInBusiness": 40,
  "openStatus": "closed now",
  "listingUrl": "https://www.yellowpages.com/austin-tx/mip/clarke-kent-plumbing-10674347",
  "ypid": "10674347",
  "isAd": false,
  "rank": 2,
  "searchTerm": "plumber",
  "location": "Austin, TX",
  "page": 1,
  "totalResults": 489,
  "searchUrl": "https://www.yellowpages.com/search?search_terms=plumber&geo_location_terms=Austin%2C+TX",
  "scrapedAt": "2026-08-16T19:50:12.450Z"
}

Field notes

• name — the business name exactly as Yellow Pages prints it, including the "DDS" and "Inc" suffixes people actually search for.
• phone — the primary number on the listing, in US display format. Present on effectively every listing.
• street — street line only. A listing filed against a city rather than an address has no street line, and neither does a mobile or service-area business. Both come back null rather than a guess.
• serviceArea — set instead of street when the listing says something like "Serving the Austin Area", which is how Yellow Pages files tradespeople with no storefront.
• city, state, zip — the address split into its parts. Where the card shows only a city line, these are still filled in and street is left null.
• website — the external site the listing links to, or null. Links that point back into yellowpages.com rather than at the business are dropped rather than passed through as a website.
• categories — every category the listing is filed under, most specific first. This is how Yellow Pages itself files the business, so it beats guessing from the name.
• rating — the average star rating. Most listings have never been reviewed, so this is null more often than not. Measured across 255 rows from a real HVAC run, rating and reviewCount were filled on 37%. That's the source's coverage, not a gap in the scrape.
• ratingIsApprox — false when the exact average was available, true on the handful of cards where only the rounded half-star display exists. Look at this before you sort by rating.
• reviewCount — how many reviews that average is built on. A 5.0 from two reviews is not a 5.0 from two hundred.
• yearsInBusiness — years trading, where the listing claims it. A rough proxy for how established a business is.
• openStatus — what the card said at the moment it was read ("open now", "closed now", "open 24 hours"), or null when no hours are on file.
• listingUrl — the listing page, with click-tracking parameters stripped, so the same business gives the same URL on every run.
• ypid — the yellowpages.com listing id. Stable, and the right key to deduplicate on when you re-run.
• rank — position in the ordinary results for that search, starting at 1. Null on sponsored rows.
• totalResults — how many listings Yellow Pages says the whole search has, not how many you asked for.
• searchTerm, location, searchUrl — which of your searches produced this row, so a multi-term run is easy to split apart afterwards.

Diagnostic rows carry "_diagnostic": true, "charged": false and an errorCode you can switch on: NO_RESULTS when a search matched nothing, INVALID_TARGET when a location was not recognised or a supplied URL was not a yellowpages.com URL, BLOCKED when every address the run tried was refused, NETWORK when the site could not be reached at all, and TIME_BUDGET when the run ran out of time before reaching a search. Each carries a plain-English error and the search it belongs to. The sample row carries "_sample": true and turns up only when the input had no search terms and no locations.

How it works

• It reads the ordinary logged-out search page, the same one a person sees, and takes every field off it. There is no second request per business, which is why a row costs a fraction of a page view rather than a page view of its own.
• Requests leave through a pool of rotating addresses that aren't billed by the gigabyte, so the traffic cost is already inside the price you see.
• Yellow Pages refuses a share of requests when it's busy, and retrying harder makes that worse. A refused page is asked for again a little later, a handful of times, with the gap growing each time. That returns the page more often than hammering it does.
• Pages are fetched several at a time rather than one after another, each from its own address.
• The exact star average and review count come from the structured data the page publishes for search engines, so the rating is the real average rather than the rounded half-star the page draws.
• Each search is paged 30 listings at a time until your row budget is reached, and listing ids already seen in the run are skipped before anything is charged.

Limitations

• United States only. A non-US location comes back as an uncharged INVALID_TARGET row rather than a guess.
• Yellow Pages caps a search at 100 pages and reports at most 3,000 results for a broad term. For more than that, split the search by ZIP or by narrower categories rather than asking for a bigger number.
• Ratings and review counts come from Yellow Pages' own reviews, and most listings have never been reviewed. On a measured 255-row run only 37% carried a rating, so plan for rating and reviewCount to be null on most rows. That's the source, not the scrape.
• Not every listing has a website, and unclaimed listings often have no street line either. Those fields come back null rather than filled with a guess.
• Email addresses are not on the search results page and are not returned. Neither are opening-hours tables, photos or review text.
• Sponsored placements are excluded unless you ask for them. When you do, they are marked "isAd": true and can repeat businesses that also appear organically. Those are deduplicated and charged once.
• openStatus is a snapshot at read time and says nothing about the hours around it.
• A busy hour can still cost you the odd page. The run retries it, spaced out, from several addresses; if it still cannot get through you get an uncharged BLOCKED row for that search rather than a silent gap. Across two batteries of 50 varied searches each, every search returned listings.
• Ceilings per run: 20 search terms, 20 locations, 30 searches in total and 3,000 rows. Split larger jobs across runs.

Questions

What counts as a location?

A US city with its state (Austin, TX, Beverly Hills, CA) or a 5-digit ZIP such as 90210. A state on its own works but returns Yellow Pages' statewide ordering, which is rarely what you want. If the site does not recognise what you typed you get one uncharged INVALID_TARGET row saying so, and the run carries on to your other searches.

How many rows will one search actually give me?

Thirty per page, and the run keeps paging until it reaches your maxItems or Yellow Pages runs out of listings. A common trade in a large metro has hundreds; a narrow term in a small town may have five. totalResults on every row tells you how deep that particular search could have gone.

Do I get charged for ads?

Only if you ask for them. includeAds is off by default, so an ordinary run charges you for ordinary directory results and nothing else. With it on, sponsored rows are charged like any other row and are marked "isAd": true so you can drop them later if you change your mind.

What happens if a search matches nothing?

You get one uncharged diagnostic row for that search with errorCode: "NO_RESULTS", and the run carries on to your other searches. You are never billed for a search that returned nothing.

Will the run fail if Yellow Pages blocks it?

No. It retries across rounds and across addresses, and if it still cannot get through you get an uncharged BLOCKED row explaining that, with the run still finishing as succeeded. A failed run would still bill you the start fee, which would mean paying to be told something went wrong.

Do I need a proxy?

No. The run brings its own egress and the cost of it is already inside the price you see. The proxyUrls field exists only for callers who specifically want traffic to leave through servers they already own.

Can I run this on a schedule?

Yes. Nothing is held between runs, so the same input is safe to repeat. Use ypid to work out which listings are new since last time. listingUrl is stable across runs for the same reason.

Can I find businesses with no website?

Filter the rows on website == null. The field is only filled when the listing actually links out to one, so a null there means the directory has no site on file for that business.