> 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://dashboard.pullbay.com/api`

## 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://dashboard.pullbay.com/api/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://dashboard.pullbay.com/api/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://dashboard.pullbay.com/api/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://dashboard.pullbay.com/api/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).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pullbay.com/api-reference/endpoints/yelp.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.