> For the complete documentation index, see [llms.txt](https://docs.pullbay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pullbay.com/api-reference/endpoints/yelp.md).

# Yelp

Yelp: places, reviews, and search. All endpoints are read-only `GET` requests and return public Yelp data — no Yelp account of your own is required.

**Base URL:** `https://api.pullbay.com/`

## Endpoints

| Endpoint                          | Description             | Pagination      |
| --------------------------------- | ----------------------- | --------------- |
| `GET /yelp/place/{id}`            | Get a place by ID       | —               |
| `GET /yelp/place/{id}/reviews`    | Get reviews for a place | Page / maxItems |
| `GET /yelp/place/handle/{handle}` | Get a place by handle   | —               |
| `GET /yelp/search`                | Search Yelp places      | Page / maxItems |

***

### Get Place

Returns a single Yelp place by its Yelp business ID.

**Request**

```http
GET /yelp/place/{id}
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter | Type   | Required | Description                                                        |
| --------- | ------ | -------- | ------------------------------------------------------------------ |
| `id`      | string | Yes      | Yelp business ID, 1–200 characters (e.g. `JQNDglh1GHuvHriHAcJ1yg`) |

**Example**

```bash
curl -G "https://api.pullbay.com/yelp/place/JQNDglh1GHuvHriHAcJ1yg" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": "JQNDglh1GHuvHriHAcJ1yg",
      "alias": "starbucks-seattle-121",
      "title": "Starbucks",
      "website": "https://www.starbucks.com/",
      "phoneNumber": "+12065551212",
      "avgRating": 3.5,
      "unroundedAvgRating": 3.4,
      "reviewCount": 105,
      "priceRange": "$$",
      "isBusinessClosed": false,
      "primaryPhoto": "https://s3-media0.fl.yelpcdn.com/bphoto/abc123/o.jpg",
      "mediaCount": 42,
      "address": { "...": "..." },
      "coordinates": { "latitude": 47.6062, "longitude": -122.3321 },
      "categories": [{ "...": "..." }],
      "operationHours": [{ "...": "..." }],
      "amenities": [{ "...": "..." }],
      "about": { "...": "..." }
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`.

***

### Get Place Reviews

Returns reviews for a Yelp place. Use `page` (1-indexed) to paginate or `maxItems` for a one-shot bulk pull (mutually exclusive).

**Request**

```http
GET /yelp/place/{id}/reviews
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter  | Type    | Required | Description                                                       |
| ---------- | ------- | -------- | ----------------------------------------------------------------- |
| `id`       | string  | Yes      | Yelp business ID, 1–200 characters                                |
| `sortBy`   | string  | No       | Sort order for reviews, 1–50 characters                           |
| `page`     | integer | No       | Page number, 1–100. Mutually exclusive with `maxItems`            |
| `maxItems` | integer | No       | One-shot bulk pull, 1–200 results. Mutually exclusive with `page` |

**Example**

```bash
curl -G "https://api.pullbay.com/yelp/place/JQNDglh1GHuvHriHAcJ1yg/reviews" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d sortBy=relevance_desc \
  -d page=1
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": "_pAYrXvfEr5MPj4eBAfjmA",
      "url": "https://www.yelp.com/biz/starbucks-seattle-121?hrid=_pAYrXvfEr5MPj4eBAfjmA",
      "rating": 5,
      "text": "Great coffee and service!",
      "language": "en",
      "date": "2026-04-30T10:00:00.000Z",
      "images": [],
      "feedback": { "...": "..." },
      "reviewer": {
        "id": "abc123",
        "name": "Jane D.",
        "profileUrl": "https://www.yelp.com/user_details?userid=abc123",
        "image": "https://s3-media0.fl.yelpcdn.com/photo/abc123/o.jpg"
      }
    }
  ],
  "pagination": { "page": 1, "hasNextPage": true, "cursor": null, "offset": null },
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Cost scales with the number of reviews returned, not the number of requests.

***

### Get Place By Handle

Returns a Yelp place by its handle / slug (the vanity URL segment used on yelp.com).

**Request**

```http
GET /yelp/place/handle/{handle}
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter | Type   | Required | Description                                                          |
| --------- | ------ | -------- | -------------------------------------------------------------------- |
| `handle`  | string | Yes      | Place handle / slug, 1–200 characters (e.g. `starbucks-seattle-121`) |

**Example**

```bash
curl -G "https://api.pullbay.com/yelp/place/handle/starbucks-seattle-121" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": "JQNDglh1GHuvHriHAcJ1yg",
      "alias": "starbucks-seattle-121",
      "title": "Starbucks",
      "website": "https://www.starbucks.com/",
      "phoneNumber": "+12065551212",
      "avgRating": 3.5,
      "unroundedAvgRating": 3.4,
      "reviewCount": 105,
      "priceRange": "$$",
      "isBusinessClosed": false,
      "primaryPhoto": "https://s3-media0.fl.yelpcdn.com/bphoto/abc123/o.jpg",
      "mediaCount": 42,
      "address": { "...": "..." },
      "coordinates": { "latitude": 47.6062, "longitude": -122.3321 },
      "categories": [{ "...": "..." }],
      "operationHours": [{ "...": "..." }],
      "amenities": [{ "...": "..." }],
      "about": { "...": "..." }
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`.

***

### Search Places

Search Yelp places by query and location. Use `page` (1-indexed) to paginate or `maxItems` for a one-shot bulk pull (mutually exclusive).

**Request**

```http
GET /yelp/search
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter  | Type    | Required | Description                                                       |
| ---------- | ------- | -------- | ----------------------------------------------------------------- |
| `query`    | string  | Yes      | Search term, 1–200 characters (e.g. `coffee`)                     |
| `location` | string  | Yes      | Location to search near, 1–200 characters (e.g. `Seattle, WA`)    |
| `sortBy`   | string  | No       | Sort order for results, 1–50 characters                           |
| `page`     | integer | No       | Page number, 1–100. Mutually exclusive with `maxItems`            |
| `maxItems` | integer | No       | One-shot bulk pull, 1–200 results. Mutually exclusive with `page` |

**Example**

```bash
curl -G "https://api.pullbay.com/yelp/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d query=coffee \
  -d location="Seattle, WA" \
  -d page=1
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": "JQNDglh1GHuvHriHAcJ1yg",
      "alias": "starbucks-seattle-121",
      "name": "Starbucks",
      "rating": 3.5,
      "reviewCount": 105,
      "priceRange": "$$",
      "phone": "+12065551212",
      "website": "https://www.starbucks.com/",
      "coordinates": { "latitude": 47.6062, "longitude": -122.3321 },
      "categories": [{ "...": "..." }],
      "images": ["https://s3-media0.fl.yelpcdn.com/bphoto/abc123/o.jpg"]
    }
  ],
  "pagination": { "page": 1, "hasNextPage": true, "cursor": null, "offset": null },
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Using `maxItems` to pull more results in one call costs proportionally more than a single page.

***

## Object schemas

### Place object

| Field                | Type    | Description                                 |
| -------------------- | ------- | ------------------------------------------- |
| `id`                 | string  | Yelp business ID                            |
| `alias`              | string  | Handle / slug used in the place's Yelp URL  |
| `title`              | string  | Place name                                  |
| `website`            | string  | Place's external website                    |
| `phoneNumber`        | string  | Contact phone number                        |
| `avgRating`          | number  | Rounded average rating                      |
| `unroundedAvgRating` | number  | Unrounded average rating                    |
| `reviewCount`        | integer | Total number of reviews                     |
| `priceRange`         | string  | Price tier (e.g. `$$`)                      |
| `isBusinessClosed`   | boolean | Whether the business is permanently closed  |
| `primaryPhoto`       | string  | URL of the primary photo                    |
| `mediaCount`         | integer | Number of photos/media items on the profile |
| `address`            | object  | Structured address fields                   |
| `coordinates`        | object  | `latitude` / `longitude`                    |
| `categories`         | array   | Business categories                         |
| `operationHours`     | array   | Hours of operation per day                  |
| `amenities`          | array   | Amenities offered (e.g. takeout, delivery)  |
| `about`              | object  | "About this business" details               |

### Review object

| Field      | Type               | Description                                         |
| ---------- | ------------------ | --------------------------------------------------- |
| `id`       | string             | Review ID                                           |
| `url`      | string             | Permalink to the review                             |
| `rating`   | number             | Rating, 1–5                                         |
| `text`     | string             | Review body                                         |
| `language` | string             | Language code of the review text                    |
| `date`     | string (date-time) | When the review was posted                          |
| `images`   | array              | Image URLs attached to the review                   |
| `feedback` | object             | Useful/funny/cool feedback counts                   |
| `reviewer` | object             | `id`, `name`, `profileUrl`, `image` of the reviewer |

### Search result object

| Field         | Type           | Description                                |
| ------------- | -------------- | ------------------------------------------ |
| `id`          | string         | Yelp business ID                           |
| `alias`       | string         | Handle / slug used in the place's Yelp URL |
| `name`        | string         | Place name                                 |
| `rating`      | number         | Average rating                             |
| `reviewCount` | integer        | Total number of reviews                    |
| `priceRange`  | string         | Price tier (e.g. `$$`)                     |
| `phone`       | string \| null | Contact phone number                       |
| `website`     | string \| null | Place's external website                   |
| `coordinates` | object         | `latitude` / `longitude`                   |
| `categories`  | array          | Business categories                        |
| `images`      | array          | Photo URLs                                 |

Note: the search result object is a lighter-weight summary than the full place object — it uses `name` instead of `title`, `phone` instead of `phoneNumber`, and omits `address`, `operationHours`, `amenities`, `about`, `isBusinessClosed`, `primaryPhoto`, and `mediaCount`. Fetch the full place by `id` or `alias` (handle) if you need those fields.

***

## Errors

All non-2xx responses share the same envelope:

```json
{
  "status": 400,
  "message": "Bad request",
  "success": false,
  "error": { "code": "BAD_REQUEST" }
}
```

| Status | Meaning                                  |
| ------ | ---------------------------------------- |
| `400`  | Bad request — missing/invalid parameters |
| `402`  | Insufficient credits                     |
| `404`  | Place or review set not found            |

## Finding Place IDs and Handles

* **Place ID**: the opaque ID Yelp assigns to a business, e.g. `JQNDglh1GHuvHriHAcJ1yg`. You'll typically get this from a prior `/yelp/search` call's `id` field.
* **Handle**: the vanity slug in a place's Yelp URL, e.g. `https://www.yelp.com/biz/starbucks-seattle-121` → `starbucks-seattle-121`. Search results also return this as `alias`.
* Both resolve the same place — use `GET /yelp/place/{id}` if you already have the ID (from a search result or a previous lookup), or `GET /yelp/place/handle/{handle}` if you only have a Yelp URL or slug.

## Pagination

* `page` and `maxItems` are mutually exclusive on both `/yelp/search` and `/yelp/place/{id}/reviews`.
* `page` returns one page at a time; check `pagination.hasNextPage` to know whether to request the next page.
* `maxItems` pulls up to the requested count in a single call instead of paging manually — useful for one-shot bulk pulls, but billed proportionally to the number of results (see each endpoint's credit cost note above).