# Yellow Pages API — US local business directory scraper: search businesses by category and city, get full business details (name, phone, address, website, rating, reviews, opening hours, years in business, categories and services) and browse any category in any US city from yellowpages.com, no API key required

> 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.
> ReefAPI engine `yellowpages` · 3 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/yellowpages/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /yellowpages/v1/search — 1 credit
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.

**Parameters:**
- `search_terms` (string, required) — What to look for — a business category, service or name ('plumber', 'italian restaurant', 'dentist', 'Joe's Pizza').
- `geo_location_terms` (string, required) — Where to search — a US 'City, ST', a ZIP code, or a neighborhood ('Austin, TX', '90210', 'Brooklyn, NY').
- `page` (integer, optional, default 1) — Result page (30 businesses per page). Page until meta.total_results is covered.

**Returns:** businesses[]{name, url, ypid, phone, address, street_address, locality, categories[], rating, review_count, years_in_business, snippet, hours[]} + meta{page, total_results, per_page, has_more, next_page}

**Example request body:**
```json
{
  "search_terms": "plumber",
  "geo_location_terms": "Austin, TX"
}
```

### POST /yellowpages/v1/detail — 1 credit
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.

**Parameters:**
- `url` (string, required) — The Yellow Pages business detail (/mip/) URL, taken from a search result's `url` field.

**Returns:** business{name, description, address, latitude, longitude, phone, website, email, rating, review_count, founding_year, years_in_business, payment_accepted, languages, hours[], services[], reviews[]{author, rating, text, date}}

### POST /yellowpages/v1/category — 1 credit
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.

**Parameters:**
- `category` (string, required) — Category slug as it appears on Yellow Pages ('restaurants', 'dentists', 'auto-repair', 'plumbers').
- `location` (string, required) — US city as 'City, ST' (e.g. 'Chicago, IL', 'Miami, FL').
- `page` (integer, optional, default 1) — Result page (30 businesses per page). Page until meta.total_results is covered.

**Returns:** businesses[]{name, url, ypid, phone, address, categories[], rating, review_count, years_in_business, snippet} + meta{page, total_results, per_page, has_more, next_page}

**Example request body:**
```json
{
  "category": "restaurants",
  "location": "Chicago, IL"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=yellowpages
- Human docs page: https://reefapi.com/docs/yellowpages
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt