# Yelp API scraper — business search, reviews, ratings, business data (price, phone, hours, amenities, photos), menus and popular dishes from yelp.com

> Fetch all reviews (with full pagination — newest, oldest, highest rated or elite first) plus the complete Yelp business profile — rating, review count, categories, price, phone, address, hours, amenities and photos. Accepts up to 39 businesses per call via their Yelp business ID.
> ReefAPI engine `yelp` · 9 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/yelp/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 /yelp/v1/business/reviews — 1 credit
Fetch all reviews (with full pagination — newest, oldest, highest rated or elite first) plus the complete Yelp business profile — rating, review count, categories, price, phone, address, hours, amenities and photos. Accepts up to 39 businesses per call via their Yelp business ID.

**Parameters:**
- `encBizIds` (array, required) — One or more Yelp business IDs. For multiple businesses, comma-separate them: id1,id2,id3 (a JSON array also works). Retrieve a business ID from the search or business/url-to-id actions — it is NOT the slug in the yelp.com/biz/ URL.
- `maxReviews` (integer, optional, default 20) — How many reviews to fetch per business (1–10000). More reviews = longer runtime.
- `sortBy` (enum, optional, default "DATE_DESC") — Review ordering. [one of: RELEVANCE_DESC, DATE_DESC, DATE_ASC, RATING_DESC, RATING_ASC, ELITES_DESC]
- `ratings` (array, optional, default [5,4,3,2,1]) — Only reviews with these star ratings, e.g. [1, 2] for negative ones. Default: all (1–5). [one of: 1, 2, 3, 4, 5]
- `language` (string, optional, default "en") — Review language code (ISO 639-1, e.g. en, es, fr, de). Yelp returns reviews written in that language.
- `includeDetail` (boolean, optional, default true) — Include the full business profile (address, phone, coordinates, amenities, hours, photos).
- `includeNotRecommended` (boolean, optional, default false) — Also fetch Yelp's 'not recommended' (filtered) reviews.
- `reviewsPerPage` (integer, optional, default 30) — How many reviews to request per page from Yelp (1–50). Higher values reduce the number of round trips for large harvests.

**Returns:** results[]{business{enc_biz_id, name, alias, url, rating, review_count, categories, phone, address, city, state, zip, latitude, longitude, amenities, hours, primary_photo_url}, reviews[]{review_id, rating, text, language, localized_date, created_at, useful_count, reactions, has_owner_reply, photos, reviewer*}} (*reviewer name and country are redacted by default; personal data is included only when you request it)

**Example request body:**
```json
{
  "encBizIds": [
    "gZz9A8k8ORC_xl0aHxtY4w"
  ],
  "maxReviews": 20
}
```

### POST /yelp/v1/business/details — 1 credit
Get the full Yelp business profile without reviews — name, categories, star rating, review count, price level, phone, full address, coordinates, hours, amenities and photo. Faster and cheaper than business/reviews when you only need the listing. Accepts up to 39 businesses per call via their Yelp business ID.

**Parameters:**
- `encBizIds` (array, required) — Yelp business ID(s). For multiple businesses, comma-separate them: id1,id2,id3 (a JSON array also works; up to 39 per request, fetched concurrently). Retrieve a business ID from the search action or business/url-to-id — it is NOT the slug in the yelp.com/biz/ URL.

**Returns:** results[]{business{enc_biz_id, name, alias, url, rating, review_count, categories, price_range, phone, address, city, state, zip, latitude, longitude, amenities[]{name,value}, hours, primary_photo_url}, rating_histogram}

**Example request body:**
```json
{
  "encBizIds": [
    "gZz9A8k8ORC_xl0aHxtY4w"
  ]
}
```

### POST /yelp/v1/search — 1 credit
Search Yelp by keyword or category in a location — just like typing 'Pizza in San Francisco, CA' on the Yelp website — with the same filters the site offers (price, rating, open-now, sort order and feature attributes). Returns a ranked list of businesses, each with its Yelp business ID, name, Yelp URL, star rating, review count, price level, categories, address and photo. Pass the business ID directly into business/reviews or business/details. Paginate with the offset parameter.

**Parameters:**
- `term` (string, required) — What to search for — a keyword, dish, service or category (e.g. 'Pizza', 'coffee shop', 'plumber', 'Mexican').
- `location` (string, required) — Where to search. Use a full, exact location like the Yelp site expects — 'San Francisco, CA' or a neighborhood, not just 'San Francisco'.
- `limit` (integer, optional, default 10) — How many businesses to return (1–40; one Yelp result page holds ~10, more spans pages).
- `offset` (integer, optional, default 0) — Pagination offset — 0 starts at the top result, 10 skips the first page, etc.
- `sort_by` (enum, optional, default "recommended") — Result ordering (Yelp's own search sorts). [one of: recommended, rating, review_count, distance]
- `price` (array, optional) — Filter by price level(s). 1=$, 2=$$, 3=$$$, 4=$$$$. Pass one or more, e.g. [1,2] for cheap+moderate. [one of: 1, 2, 3, 4]
- `open_now` (boolean, optional, default false) — Only businesses open at the time of the search.
- `min_rating` (enum, optional) — Only businesses at or above this star rating. [one of: 3.5, 4, 4.5, 5]
- `attributes` (array, optional) — Extra Yelp filter attributes (advanced). Common values: RestaurantsReservations, RestaurantsDelivery, RestaurantsTakeout, Deals, GoodForKids, DogsAllowed, WheelchairAccessible, BusinessParking, OutdoorSeating. Pass one or more; combined with the filters above.

**Returns:** results[]{enc_biz_id, name, slug, url, rating, review_count, price, price_level, categories[], address, city, state, neighborhoods[], image} + meta{parse_source, offset, limit}

**Example request body:**
```json
{
  "term": "Pizza",
  "location": "San Francisco, CA",
  "limit": 10
}
```

### POST /yelp/v1/popular_dishes — 1 credit
Get a restaurant's popular dishes from Yelp — the 'Popular dishes' section shown on the Yelp business page — returning each dish's name and photo. Identify the restaurant by its Yelp business URL, its Yelp business ID (from the search or business details actions), or its Yelp slug. Restaurant pages only; returns an empty list when Yelp shows no popular dishes for that restaurant.

**Parameters:**
- `business_url` (string, optional) — The restaurant's Yelp business page URL (any yelp.com/biz/… link). Provide this OR business_id OR slug.
- `business_id` (string, optional) — The restaurant's Yelp business ID — as returned by the search or business/details actions (e.g. v1DHGRNCH9247WLYoaoA9A).
- `slug` (string, optional) — The restaurant's Yelp slug (the part after /biz/ in the URL).
- `limit` (integer, optional, default 20) — Max dishes to return (1–50).

**Returns:** dishes[]{name, image, photo_id} + count

### POST /yelp/v1/menus — 1 credit
Get a restaurant's menu from Yelp when Yelp hosts it — returning menu sections with each item's name, description, price and photo. Identify the restaurant by its Yelp business URL, Yelp business ID, or slug. Only menus hosted on Yelp are returned; many restaurants link to an external menu, which Yelp has no structured data for — `menu_available` is false in those cases.

**Parameters:**
- `business_url` (string, optional) — The restaurant's Yelp business page URL (any yelp.com/biz/… link).
- `business_id` (string, optional) — The restaurant's Yelp business ID (from search or business details).
- `slug` (string, optional) — The restaurant's Yelp slug (the part after /biz/ in the URL).

**Returns:** sections[]{section, items[]{name, description, price, image}} + section_count + item_count + menu_available

### POST /yelp/v1/business/photos — 1 credit
Get a Yelp business's photos — the images shown on its Yelp page, with captions and categories (food, menu, interior, etc.) where Yelp provides them. Identify the business by its Yelp business URL, Yelp business ID, or slug.

**Parameters:**
- `business_url` (string, optional) — The business's Yelp page URL (any yelp.com/biz/… link). Provide this OR business_id OR slug.
- `business_id` (string, optional) — The business's Yelp business ID (from the search or business/details actions).
- `slug` (string, optional) — The business's Yelp slug (the part after /biz/ in the URL).
- `limit` (integer, optional, default 60) — Max photos to return (1–200).

**Returns:** photos[]{url, caption, category} + count

**Example request body:**
```json
{
  "slug": "tonys-pizza-napoletana-san-francisco",
  "limit": 8
}
```

### POST /yelp/v1/review_highlights — 1 credit
Get a Yelp business's review highlights — the recurring phrases reviewers mention (e.g. 'happy hour', 'great service'), each with a sample snippet from a real review. A fast at-a-glance read on what the business is known for. Identify the business by its Yelp business URL, Yelp business ID, or slug.

**Parameters:**
- `business_url` (string, optional) — The business's Yelp page URL. Provide this OR business_id OR slug.
- `business_id` (string, optional) — The business's Yelp business ID (from search or business/details).
- `slug` (string, optional) — The business's Yelp slug (the part after /biz/ in the URL).
- `limit` (integer, optional, default 15) — Max highlights to return (1–30).

**Returns:** highlights[]{phrase, snippet} + count

**Example request body:**
```json
{
  "slug": "tonys-pizza-napoletana-san-francisco",
  "limit": 6
}
```

### POST /yelp/v1/business/url-to-id — 1 credit
Convert any yelp.com/biz/… business page URL into the Yelp business ID used by business/details, business/reviews, popular_dishes and menus.

**Parameters:**
- `business_url` (string, required) — Any yelp.com/biz/… business page URL (any subdomain). Returns that business's Yelp business ID.

**Returns:** {enc_biz_id, name, slug, url}

### POST /yelp/v1/business/search — 1 credit
Find a Yelp business by name (plus optional location) and return its Yelp business ID, name and Yelp URL. Pass the business ID straight into business/reviews or business/details. No Yelp account required.

**Parameters:**
- `name` (string, required) — Business name to look up on Yelp — e.g. 'Blue Bottle Coffee'.
- `location` (string, optional) — City / neighborhood to disambiguate same-named branches (strongly recommended).
- `limit` (integer, optional, default 5) — Max ranked candidate matches to return (1–10).
- `resolveAll` (boolean, optional, default false) — Resolve the Yelp business ID for every returned candidate (uses more calls). Default: resolve only the top match.

**Returns:** results[]{enc_biz_id, name, slug, url, subtitle, name_similarity} (ranked by name match; the top result's business ID is always resolved)

**Example request body:**
```json
{
  "name": "Blue Bottle Coffee",
  "location": "San Francisco"
}
```

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