---
agentTools:
  projectIndex: https://docs.developer.yelp.com/llms.txt
---

# Yelp Insights Technical Overview

***

title: "Yelp Insights"
slug: "yelp-insights"
excerpt: "Retrieve real-time Yelp data to better understand market trends and consumer preferences."
----------------------------------------------------------------------------------------------------

Yelp Insights provides a means for you to ingest structured data about Yelp's business listings. This data can be accessed via:

* **API**  Various REST endpoints for on-demand queries
* **Feed**  Daily/monthly JSON files delivered to an S3 bucket

***

## Getting Started

### API Access

You can self-serve API credentials:

1. [Create a Fusion API app](https://www.yelp.com/developers/v3/manage_app)
2. Email your `client_id` to your Yelp account rep so we can tag your account accordingly

The data access you receive will be aligned with your executed partnership agreement with Yelp.

### Feed Access

After contract execution, Yelp will configure the feed system and email your S3 credentials. The feed is delivered to a bucket on Yelp's account that we grant you access to.

**S3 path format:**

```
s3://yelp-syndication/{name}/YYYYMMDD_businesses.json.gz
```

**Permissions granted:**

| Permission   | Scope                                                |
| ------------ | ---------------------------------------------------- |
| `ListBucket` | All keys in `yelp-syndication` prefixed by `{name}/` |
| `GetObject`  | All keys matching `yelp-syndication/{name}/*`        |

**Feed population options:**

Feeds are populated by one of these options (not both):

1. **Set of filters**  e.g. Category: Restaurants, Country: US, State: TX, CA, FL, AZ
2. **Explicit list of Yelp business\_ids**  Use the [Business Search](https://docs.developer.yelp.com/reference/v3_business_search) or [Business Match](https://docs.developer.yelp.com/reference/v3_business_match) endpoints to find relevant businesses, then subscribe to the relevant `id` with `subscription_types=YELP_KNOWLEDGE`

> 📘 Feed-only partners
>
> If you're using option 1 (filters), you can skip the API-specific sections below.

***

## Authentication

Yelp's Fusion API uses a Bearer token. Your API key is 128 characters long.

**Example request:**

```bash
curl --request GET \
     --url 'https://api.yelp.com/v3/businesses/search?location=San%20Francisco&term=Dinner' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer YOUR_128_CHARACTER_API_KEY'
```

> 📘 More details
>
> See the full [Authentication documentation](https://docs.developer.yelp.com/docs/fusion-authentication).

***

## Your First API Call

### Step 1: Discover Businesses

Use these endpoints to resolve businesses to Yelp IDs:

| Endpoint                                                                               | Use case                                                              |
| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [**Business Search**](https://docs.developer.yelp.com/reference/v3_business_search)    | Find Yelp pages using filters (location, category, price, attributes) |
| [**Business Match**](https://docs.developer.yelp.com/reference/v3_business_match)      | Match known business details (name, address, phone) to a Yelp page    |
| [**Phone Search**](https://docs.developer.yelp.com/reference/v3_business_phone_search) | Retrieve all Yelp pages linked to a phone number                      |

[Here's](https://docs.developer.yelp.com/docs/business-matching-guidance) more detailed information on how to match to a Yelp business id.

**Example searching by location and term:**

```bash
curl --request GET \
     --url 'https://api.yelp.com/v3/businesses/search?location=San%20Francisco&term=Dinner' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {api_key}'
```

**Example response:**

```json
{
  "businesses": [
    {
      "id": "QueFVMcMlT-6aZFv2M47mg",
      "alias": "bottega-san-francisco-2",
      "name": "Bottega",
      "location": {
        "address1": "",
        "address2": "",
        "address3": "",
        "city": "San Francisco",
        "zip_code": "94158",
        "country": "US",
        "state": "CA",
        "display_address": [
          "San Francisco, CA 94158"
        ]
      },
      "distance": 0.9359428980202893
    }
  ]
}
```

### Step 2: Retrieve Insights Data

Use the `id` from the discovery response to query the insights endpoints below.

***

## Core Endpoints

| Endpoint                                                                                                        | Data Available                                                                          |
| --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [**Business Details**](https://docs.developer.yelp.com/reference/v3_business_info)                              | POI data, operating data, viability score, year-over-year growth, photos & captions     |
| [**Private Reviews**](https://docs.developer.yelp.com/reference/v3_business_reviews)                            | Yelp star rating, full-text reviews (most recent 200), review IDs                       |
| [**Food & Drink Insights**](https://docs.developer.yelp.com/reference/v3_get_business_food_and_drinks_insights) | Food offered, drinks offered, food ingredients, count of mentions                       |
| [**Engagement Metrics**](https://docs.developer.yelp.com/reference/v3_get_businesses_engagement)                | Bundled scores factoring consumer connection signals & traffic                          |
| [**Reporting API**](https://docs.developer.yelp.com/reference/create_daily_reports_v3)                          | Daily/monthly activity metrics (URL clicks, calls, search appearances, bookmarks, etc.) |
| [**Risk Signal Insights**](https://docs.developer.yelp.com/reference/v3_get_business_risk_signals_insights)     | Consumer intent metrics, risk signal data                                               |
| [**Business Insights**](https://docs.developer.yelp.com/reference/v3_businesses_insights)                       | Safety score, customer experience score                                                 |
| [**Respond to Reviews**](https://docs.developer.yelp.com/reference/create_review_response)                      | Business owner responses to consumer reviews                                            |
| [**Business Subscriptions**](https://docs.developer.yelp.com/reference/create_business_subscriptions)           | Toggle on/off Yelp data access for Yelp profile pages                                   |

> 📘 Access note
>
> Insights data endpoints require special permissions. Your Yelp account team will configure access based on your partnership agreement.

***

## Billing

Broadly, Yelp bills according to how many **unique `biz_id`s** you've accessed across all endpoints, not per API call. Defer to your contract as the source of truth for billing.

**Examples:**

| Scenario                                                                             | Billed Usage |
| ------------------------------------------------------------------------------------ | ------------ |
| `biz_id` 123 queried via all 5 endpoints                                             | 1            |
| `biz_id` 123 queried via Business Details + `biz_id` ABC queried via Private Reviews | 2            |

***

## Error Handling

Common error codes you may encounter:

| Code | Cause                                             | Suggested Action                                   |
| ---- | ------------------------------------------------- | -------------------------------------------------- |
| 429  | Too many requests/day or requests/second          | Contact your Yelp rep to request a new rate limit  |
| 401  | Your API key may not have access to this endpoint | Verify your account permissions with your Yelp rep |
| 403  | Your IP may be blocked                            | Test the same request from a different machine     |
| 500  | Server error (rare)                               | Retry the request                                  |

Error codes and reasons are documented on each endpoint's reference page.

> 🚧 When requesting support
>
> If you can't resolve an error, reach out to your Yelp rep and assigned solutions engineer directly. Include:
>
> * Full request and response
> * Timestamp
> * Number of occurrences and timeframe
> * Affected `biz_id`(s)

***

## Operational Considerations

### General

* The `id` field is Yelp's `business_id` and is the main key to track. Include it in any troubleshooting requests.
* To find a Yelp.com page for one-off troubleshooting: `https://www.yelp.com/biz/{id}`

### API

* The data available to your API key aligns with your partnership agreement.
* We suggest daily polling to ensure you have the most up-to-date content and can detect any review/photo removals.

### Feed

* We suggest refreshing data (especially reviews) daily for the most up-to-date information.
* Reviews and photos that are removed will disappear from subsequent feed files.
* Each feed file is an **exhaustive update** it contains the full current dataset, not just a changeset.

***

## Troubleshooting Template

When reaching out to your Yelp rep with an issue, use this format:

```
Date: MM/DD
Issue: [Description of the problem with your client_id]
Yelp business IDs: [Affected biz_ids]
How to recreate (include full API request and response):

Request:
https://api.yelp.com/v3/businesses/{biz_id}

Response:
{
  "error": {
    "code": "UNAUTHORIZED_API_KEY",
    "description": "The API key provided is not currently able to query this endpoint."
  }
}

Date this was first observed or date when the expected behavior changed.
```

***

## Next Steps

### API Partners

1. [Create an API key](https://www.yelp.com/developers/v3/manage_app) and send your `client_id` to your Yelp rep
2. If you're not yet an official partner with an executed agreement, [learn more here](https://business.yelp.com/data/products/insights-api/)
3. Yelp configures your account
4. Familiarize yourself with the various endpoints
5. Build your integration
6. Launch

### Feed Partners

1. Your Yelp account rep will intro a solutions engineer post-contract signature
2. Yelp solutions engineer will configure and share your S3 credentials
3. Set up your ingestion pipeline
4. Launch