Yelp Insights Technical Overview

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
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:

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 or 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:

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.

Your First API Call

Step 1: Discover Businesses

Use these endpoints to resolve businesses to Yelp IDs:

Here's more detailed information on how to match to a Yelp business id.

Example searching by location and term:

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:

{
  "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

📘

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_ids you've accessed across all endpoints, not per API call. Defer to your contract as the source of truth for billing.

Examples:

Error Handling

Common error codes you may encounter:

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 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
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