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 candidate businesses, verify each candidate is the business you intend to work with, then subscribe to the verified 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

Working with Yelp Insights is a two-step process:

1. Discover candidate Yelp business IDs, then verify which candidates are the businesses you're looking for.
2. Retrieve insights data for the business IDs you've verified.

You decide which business IDs move from Step 1 to Step 2.

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 via biz match endpoint:

curl --request GET \
     --url 'https://api.yelp.com/v3/businesses/matches?name=Delarosa&address1=2175%20Chestnut%20St&city=San%20Francisco&state=CA&country=US&limit=3&match_threshold=default' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {api_key}'

Example response:

{
  "businesses": [
    {
      "id": "QQkroHtwS96-dzMpT4a-DA",
      "alias": "delarosa-marina-san-francisco",
      "name": "Delarosa Marina",
      "location": {
        "address1": "2175 Chestnut St",
        "address2": "",
        "address3": "",
        "city": "San Francisco",
        "zip_code": "94123",
        "country": "US",
        "state": "CA",
        "display_address": [
          "2175 Chestnut St",
          "San Francisco, CA 94123"
        ]
      },
      "coordinates": {
        "latitude": 37.800287,
        "longitude": -122.439110224537
      },
      "phone": "+14156737100",
      "display_phone": "(415) 673-7100"
    }
  ]
}

Verify matches before you use them

Discovery endpoints return candidates, not confirmed matches. Business Match is built to help you find likely Yelp pages for businesses you already know about. Matching is probabilistic, so results can include businesses that aren't the one you're looking for (false positives), and sometimes the right business won't be returned at all (false negatives).

Before you use a business ID in Step 2 or subscribe to it, confirm it's the business you intend to work with. We recommend checking at least:

If no candidate passes your checks, treat the result as no match. Don't fall back to the first result returned.

🚧

Don't connect Step 1 directly to Step 2

We strongly recommend placing your own verification logic between discovery and data retrieval, rather than automatically retrieving data for or subscribing to every ID a discovery endpoint returns. Your integration is responsible for deciding which business IDs to use. Data retrieved for, or subscriptions to, incorrectly matched businesses count toward your usage like any other business ID.

To spot-check a candidate by hand, open https://www.yelp.com/biz/{id}.

Step 2: Retrieve Insights Data

Use the id of each business you verified in Step 1 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. Defer to your contract as the source of truth for billing, including which endpoints count toward billed usage.

Discovery endpoints (Business Search, Business Match, Phone Search) help you find candidate business IDs. You choose which of those IDs to retrieve insights data for or subscribe to, so verifying candidates first (see Verify matches before you use them) keeps your billed usage limited to the businesses you actually want.

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}
• Store the inputs you sent and the candidate you accepted for each business ID. This makes it easy to audit matches later and speeds up troubleshooting.

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.
• Discovery results can change over time as Yelp's data and matching improve. Re-verify a match before relying on it if the business details you hold have changed.

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, including a verification step between discovery (Step 1) and data retrieval (Step 2)
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. If you're populating your feed with an explicit list of business IDs, verify each ID before subscribing
4. Set up your ingestion pipeline
5. Launch