Yellow Pages API & Scraper
The Yellow Pages API returns US business-directory data as clean JSON.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
The primary search endpoint returns businesses with name, URL, YPID, phone, address, categories and rating, and you can pull a detail and browse a category. It is built for lead generation, local-data products and B2B enrichment that need Yellow Pages data without a scraper. One ReefAPI key, one shared credit pool, the standard envelope.
Listing identity, the numbers that are not what they look like, and the US-only boundary
Three things about this directory catch callers out: a single result page repeats businesses, total_results is a capped headline rather than a count, and a non-US location is silently remapped instead of rejected. The address also arrives in two different shapes depending on which action you called. Everything below came from live calls on 2026-08-27.
| Field or limit | Behavior | Measured |
|---|---|---|
| ypid | Numeric string, 8-9 digits, the same number that ends the /mip/ URL slug | "10674347" in https://www.yellowpages.com/austin-tx/mip/clarke-kent-plumbing-10674347. This is the stable key; the url itself carries a ?lid= tracking parameter that changes between calls. |
| Duplicate rows | The same ypid can appear more than once on a single page | plumber in Austin, TX page 1: 43 rows, 28 unique ypid. restaurants in Chicago, IL: 34 rows, 29 unique. Dedupe on ypid. |
| meta.total_results | Saturates at 3000, so it is a headline rather than a count | dentist / 90210 reported 3000 and restaurants / Chicago, IL reported 3000, while plumber / Austin, TX reported a genuine 490. |
| Paging | meta.per_page is 30 and pages genuinely advance | plumber / Austin, TX page 1 and page 2 shared zero ypid values. meta also carries page, has_more and next_page. |
| phone | US display string with parentheses and a space, not E.164 | "(512) 766-0970". Toll-free lead-gen numbers look identical in shape: "(855) 566-6978", "(833) 947-9225". |
| Address on a search row | Split into street_address and locality; there is no address key on a search row | street_address "9511 Brown Ln" with locality "Austin, TX 78754", so locality carries city, state and ZIP together. |
| Address on a detail row | One joined string on the address key | "1408 W Ben White Blvd, Austin, TX 78704", alongside latitude 30.228342 and longitude -97.78136. |
| hours[] | Array of schema.org opening-hours strings, one entry per distinct block | ["Mo-Fr 09:00-17:00"], ["We-Sa 11:00-22:00", "Su 11:00-23:00"], and a bare ["Mo-Su"] when the listing publishes days but no times. |
| rating | Float on a search row, integer on a detail row, null when review_count is null | 3.0 with review_count 15 on the search row; the same business returned rating 3 on detail. |
| founding_year vs years_in_business | String against integer, and the two agree | Paterno's Pizza: founding_year "1954", years_in_business 72. Clarke Kent Plumbing: "1986" and 40. |
| category slug | Must be a real Yellow Pages slug; a bad one is an error, not an empty list | category "not-a-real-category-xyz" with "Chicago, IL" returned NOT_FOUND naming the 404'd URL /chicago-il/not-a-real-category-xyz, which also shows how the location is slugified. |
geo_location_terms is United States only, and a foreign place is remapped rather than refused. "Toronto, ON" returned ok:true with 30 plumbers in Bergholz, Steubenville and Scio, Ohio, because ON was resolved against US state data. Always check the locality on the rows you get back before trusting a location you have not verified.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/yellowpages/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"search_terms": "plumber",
"geo_location_terms": "Austin, TX"
}
}{
"ok": true,
"meta": {
"api": "yellowpages",
"endpoint": "search",
"mode": "live",
"latency_ms": 5527.9,
"record_count": 45,
"bytes": 290816,
"cache_hit": false,
"completeness_pct": 100,
"stop_reason": "limit_reached",
"page": 1,
"total_results": 491,
"per_page": 30,
"has_more": true,
"next_page": 2,
"charged_credits": 1,
"version": "1.0.0"
},
"data": {
"businesses": [
{
"name": "Best Home Savings",
"url": "https://www.yellowpages.com/nationwide/mip/best-home-savings-580143680?lid=1002194693880",
"ypid": "580143680",
"phone": null,
"street_address": null,
"locality": null,
"categories": [
"Plumbers",
"Water Heaters",
"Plumbing Contractors-Commercial & Industrial"
],
"rating": null,
"review_count": null,
"years_in_business": null,
"snippet": null
},
{
"name": "ARS Rescue Rooter",
"url": "https://www.yellowpages.com/conroe-tx/mip/ars-rescue-rooter-561030332?lid=1002194107250",
"ypid": "561030332",
"phone": null,
"street_address": null,
"locality": null,
"categories": [
"Plumbers",
"Air Conditioning Contractors & Systems",
"Furnaces-Heating"
],
"rating": null,
"review_count": null,
"years_in_business": null,
"snippet": null
},
{
"name": "Will Fix It",
"url": "https://www.yellowpages.com/san-antonio-tx/mip/will-fix-it-494833978?lid=1002195671661",
"ypid": "494833978",
"phone": null,
"street_address": null,
"locality": null,
"categories": [
"Plumbers",
"Furnaces-Heating",
"Air Conditioning Contractors & Systems"
],
"rating": null,
"review_count": null,
"years_in_business": null,
"snippet": null
}
]
}
}What the Yellow Pages API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | Search the Yellow Pages business directory by category/keyword and US location. Returns up to 30 businesses per page with name, phone, address, categories, star rating, review count, years in business, a 'From Business' snippet and the detail URL. Paginate with `page`; meta.total_results gives the full match count. | Support teams call search to search the Yellow Pages business directory by category/keyword and US location. | search_terms, geo_location_terms, page |
| detail | Full business profile from a Yellow Pages detail URL (the `url` of a search result): name, description, full address, geo coordinates, phone, website, email, rating + review count, years in business / founding year, payment methods, languages, opening hours, the list of services offered and recent customer reviews. | Reputation platforms call detail to get full business profile from a Yellow Pages detail URL (the `url` of a search result). | url |
| category | Browse every business in a Yellow Pages category for a US city — e.g. all restaurants in Chicago, all dentists in Miami. Same business fields as search, paginated. Use this when you want a city-wide category list rather than a keyword search. | Market researchers call category to get browse every business in a Yellow Pages category for a US city. | category, location, page |
Call search from your stack
curl -X POST https://api.reefapi.com/yellowpages/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"search_terms":"plumber","geo_location_terms":"Austin, TX"}'import requests
r = requests.post(
"https://api.reefapi.com/yellowpages/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"search_terms": "plumber",
"geo_location_terms": "Austin, TX"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/yellowpages/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"search_terms": "plumber",
"geo_location_terms": "Austin, TX"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.yellowpages.search with {"search_terms":"plumber","geo_location_terms":"Austin, TX"}.Who uses this API and why
- Lead-gen tools call search to build business lists by category and city.
- Enrichment uses detail to attach phone and address to a record.
- Analysts use category to size a local market.
Questions developers ask before integrating
Why does one page return 43 rows when per_page says 30?
Because the page carries sponsored placements alongside the organic thirty, and both are parsed. A live plumber search in Austin, TX returned 43 rows containing only 28 distinct ypid values, with several businesses appearing twice, once in the ad block and once in the list. Dedupe on ypid before you count anything.
What are the /nationwide/ results at the top of a search?
National lead-generation advertisers rather than local businesses. Three of the 43 rows on the Austin plumber page had /nationwide/ in the url, a toll-free (855) or (833) phone, and null for street_address, locality, rating, review_count, years_in_business and snippet. Filter them out by testing for "/nationwide/" in url, or by requiring street_address to be non-null.
Is total_results a real match count?
Only below the cap. Two different broad searches, dentists in 90210 and restaurants in Chicago, IL, both reported exactly 3000, which is a ceiling rather than a coincidence. A narrower search reported 490, which is a genuine figure. Treat 3000 as "at least 3000" and page until has_more turns false.
Can I search a city outside the United States?
No, and the failure is silent. "Toronto, ON" came back ok:true with 30 rows and total_results 80, all of them plumbers in Ohio towns like Bergholz and Steubenville, because ON was matched against US state data instead of Ontario. There is no error and no warning field, so validate the locality on the first row against what you asked for.
What does detail add over a search row?
A lot: description, latitude, longitude, website, email, payment_accepted, languages, services[] and reviews[]. A live detail call on Clarke Kent Plumbing returned latitude 30.228342, longitude -97.78136, website http://www.clarkekentplumbing.com, email [email protected], 28 services and 10 reviews. detail takes the url from a search row, so reaching those fields always costs two calls.
Why are payment_accepted and languages strings instead of arrays?
They are passed through as the listing publishes them, comma-joined and unnormalized. Measured: "check, amex, discover, visa, cash, master card" for one business and "amex, visa, cash, discover, mastercard" for another, so the same brand appears as both master card and mastercard. languages behaves the same way ("English, Italian, Spanish", or "Spanish", or null). Split on comma and normalize yourself.
A business has 148 services but only 6 reviews. Is that right?
Yes. services[] is the business's own self-declared service list from its listing page, so its length reflects how thoroughly the owner filled in the form and not the size of the business. Measured on three Chicago restaurants: 148 services with 6 reviews, 2 services with 2 reviews, and 2 services with no reviews and a null rating at all. Never infer scale or activity from the services count.
How do I get the category slug right for the category action?
Use the slug exactly as it appears in a yellowpages.com URL: lowercase and hyphenated, such as restaurants, dentists, auto-repair or plumbers. A wrong slug is a hard failure rather than an empty result, and "not-a-real-category-xyz" returned error code NOT_FOUND with the 404'd URL in the message. That message also shows how location is slugified, with "Chicago, IL" becoming chicago-il, which is a quick way to confirm the city was understood.
What is the Yellow Pages API?
Yellow Pages API is a ReefAPI endpoint group for yellow pages It returns live JSON through POST requests under /yellowpages/v1.
Is the Yellow Pages API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Yellow Pages calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Yellow Pages login or account?
No login to Yellow Pages is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Yellow Pages data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Yellow Pages API use?
Yellow Pages actions currently cost 1 credit per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call Yellow Pages from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call yellowpages actions with the same key, credit pool and JSON envelope used by normal REST requests.