Read Yellow Pages business listings with one API
The Yellow Pages API returns US business-directory data as clean JSON.
3 active endpoints. Every call is 1 credit.
- POST/yellowpages/v1/search
- POST/yellowpages/v1/detail
- POST/yellowpages/v1/category
What Yellow Pages endpoints does ReefAPI ship?
3 live read endpoints. Read-only data API: no writes, no account actions, no dashboard access on the target site.
Yellow Pages API
3 of 3 endpoints, ready to run
The directory search: name, phone, street address, categories, opening hours and the listing id, for a keyword in a US city.
{ "ok": true, "meta": { "api": "yellowpages", "endpoint": "search", "mode": "live", "latency_ms": 2733.3, "record_count": 43, "cache_hit": false, "completeness_pct": 100 }, "data": { "businesses": [ { "name": "Best Home Savings", "url": "https://www.yellowpages.com/nationwide/mip/best-home-savings-580143680?lid=1002194693880", "ypid": "580143680", "phone": "(855) 566-6978", "street_address": null, "locality": null, "categories": [ "Plumbers", "Water Heaters", "Plumbing Contractors-Commercial & Industrial" ], "rating": null, "review_count": null, "years_in_business": null, "snippet": null, "hours": [ "Mo-Su" ] }, { "name": "ARS Rescue Rooter", "url": "https://www.yellowpages.com/conroe-tx/mip/ars-rescue-rooter-561030332?lid=1002194107250", "ypid": "561030332", "phone": "(833) 947-9225", "street_address": null, "locality": null, "categories": [ "Plumbers", "Air Conditioning Contractors & Systems", "Furnaces-Heating" ], "rating": null, "review_count": null, "years_in_business": null, "snippet": null, "address": "Conroe, TX 77303", "hours": [ "Mo-Su" ] }, { "name": "Will Fix It", "url": "https://www.yellowpages.com/san-antonio-tx/mip/will-fix-it-494833978?lid=1002195671661", "ypid": "494833978", "phone": "(833) 947-9225", "street_address": null, "locality": null, "categories": [ "Plumbers", "Furnaces-Heating", "Air Conditioning Contractors & Systems" ], "rating": null, "review_count": null, "years_in_business": null, "snippet": null, "address": "San Antonio, TX 78247" } ] } }
How the Yellow Pages API works
Yellow Pages is a normal ReefAPI surface — the same four rules that hold for every other engine on the key.
No OAuth app, no request signing, no per-site account. One key covers all 185 engines.
Every route is a POST with a JSON body. Parameters are validated against the published schema before anything is charged.
Credits, not seats. Failed and blocked calls are never charged, and cache hits cost nothing.
One envelope everywhere. meta carries latency_ms, record_count and the endpoint that answered.
Sweep a city, then enrich what matters
The search rows are cheap and wide; the detail call is where the website, email, coordinates and services live. Sweeping first and enriching second keeps the credit count proportional to the businesses you actually care about.
{"search_terms": "plumber", "geo_location_terms": "Austin, TX"}About 30 to 43 rows a page. Increment page until a page comes back with zero businesses — that is the only stop signal.
{"url": "<the url of a row you want>"}One credit per business. This is the only call that returns the website, the email and the coordinates.
A whole city's listings for one category in under twenty credits, and enrichment priced per business rather than per sweep.
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"}'{
"ok": true,
"data": { … },
"meta": {
"api": "yellowpages",
"endpoint": "search",
"mode": "live",
"latency_ms": …,
"record_count": …
},
"error": null
}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.
A directory first, a review source second
Measured on 2026-08-27 across plumbers in Austin, restaurants in Chicago and restaurants in New York, by paging each query until the rows ran out.
Against us, and it matters given the category this engine sits in: a rating and a review count were present on 15 of 43 Austin plumbers, 15 of 30 New York restaurants, and 0 of 34 Chicago restaurants. Most Yellow Pages listings carry no reviews at all.
Against us: detail returns at most ten reviews and offers no way to ask for more. A New York restaurant that reports 60 reviews returned 10. If your job is every review of a business, this is the wrong engine — it is a directory that happens to carry ratings.
Page 1 returned 43 rows and pages 2 through 17 returned 30 each; from page 18 the response is zero businesses with ok:true, although the schema accepts page up to 100. About 520 businesses per query, and the only stop signal is an empty page.
Against us: the response carries the businesses array and nothing else. The page, total_results and has_more fields the schema describes were not present, so a loop cannot ask how many results exist — it has to page until empty.
Flat 1 credit per call, so a full 17-page sweep is 17 credits and each enrichment is 1 more. Name, listing url, listing id, phone and categories were on 100% of rows; street address on 40 of 43, opening hours on 35, years in business on 19 and the description snippet on 10.
What people build with Yellow Pages
The jobs this data is most often used for.
endpoints
credit per call
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.
What Yellow Pages data costs
The cheapest call here is 1 credit, so $15/mo (Pro) buys 10,000 of them — $1.50 per 1,000 credits. Credits roll over and never expire, and failed or blocked calls are not charged.
Full pricing →- 1,000 free credits on signup, no card
- One key, all 185 APIs, one credit pool
- Failed and blocked calls are never charged
- Credits roll over and never expire
Call it in two lines
Sign up, get 1,000 credits and one key that works on every engine. Then this is the whole protocol.
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"])Have a question? We got answers.
The questions people actually ask before wiring up Yellow Pages.
Get a free key →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, and 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.
14 Reputation & Reviews APIs on the same key
One key, one credit pool, one response envelope. If you are pulling Yellow Pages, you are one call away from the rest of the category — no second contract, no second integration.
Try it on your own data before you pay anything
The call above is the real endpoint, not a recording. A free key gives you 1,000 credits, the other 184 APIs, and the same envelope everywhere.
Endpoints, parameters and credit costs on this page are read from the live catalog and cannot drift from what the API accepts. Field notes were captured on 2026-08-27.