> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mavera.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Yelp

> Integrate Mavera with Yelp — business discovery for market research, review excerpt sentiment, category trend analysis, and competitive focus group stimulus

## Overview

Pull data from the **Yelp Fusion API** (Business Search, Business Details, Reviews, Categories) → analyze with **Mavera** (Mave Agent, Chat, Focus Groups, Personas) → turn Yelp's local business data into competitive intelligence, consumer trend analysis, and persona-validated market research.

<Info>
  **Yelp Fusion API** — Base URL: `https://api.yelp.com/v3/`. Auth: **API Key as Bearer token**. Rate limits: **3-15+ QPS** (paid tiers); **5,000 total calls** on free trial. Pagination via `offset` param (max 1,000 results per search).
</Info>

***

## Prerequisites

<Steps>
  <Step title="Yelp API key">Create an app at [Yelp Fusion](https://www.yelp.com/developers/v3/manage_app). Free tier includes 5,000 API calls. Paid tiers offer 3-15+ QPS.</Step>
  <Step title="Mavera API key">Get your key from [Mavera dashboard](https://app.mavera.io/settings/api-keys).</Step>

  <Step title="Environment variables">
    ```bash theme={"dark"}
    export YELP_API_KEY="your_yelp_api_key"
    export MAVERA_API_KEY="mvra_live_xxxxx"
    ```
  </Step>
</Steps>

***

## Jobs

| # | Job                                                        | Yelp Data                   | Mavera Surface                    | Output                         |
| - | ---------------------------------------------------------- | --------------------------- | --------------------------------- | ------------------------------ |
| 1 | [Business Discovery → Market Research](market-research)    | Search by category/location | Mave Agent                        | Competitive landscape analysis |
| 2 | [Review Excerpt Sentiment](review-sentiment)               | Review excerpts             | Chat (quick sentiment)            | Rapid sentiment classification |
| 3 | [Category Trend Analysis](category-trend-analysis)         | Trending businesses         | Mave Agent                        | Consumer trend report          |
| 4 | [Local Business → Focus Group Stimulus](local-focus-group) | Competitor profiles         | Personas + Focus Groups (Ranking) | Consumer preference ranking    |

***

## Rate Limits & Production Notes

| Yelp Endpoint   | Limit                         | Strategy                                            |
| --------------- | ----------------------------- | --------------------------------------------------- |
| Business Search | 3-15+ QPS (paid); 5,000 trial | Cache search results; narrow with category/location |
| Business Detail | Counts against total quota    | Cache profiles — they change slowly                 |
| Reviews         | Max 3 excerpts per business   | Directional signal only; don't over-interpret       |
| Autocomplete    | Low priority endpoint         | Useful for UX, not analysis                         |

<Warning>
  Yelp's free tier has a **hard cap of 5,000 API calls total** (not per month — total). Use the trial for prototyping, then upgrade to a paid plan for production. Cache aggressively — business profiles rarely change day-to-day.
</Warning>

**Checklist:**

* Auth: API key as `Bearer` token (not Basic auth)
* Business search returns max 1,000 results (`offset` + `limit` ≤ 1000)
* Reviews endpoint returns max 3 excerpts — this is a Yelp ToS limitation
* Never scrape Yelp pages — it violates their ToS and will get you blocked
* Category aliases must be exact — reference the [full category list](https://www.yelp.com/developers/documentation/v3/all_category_list)
* Monitor Mavera credits at [Dashboard](https://app.mavera.io/settings/usage)

***

<CardGroup cols={3}>
  <Card title="All Integrations" icon="plug" href="/integrations" />

  <Card title="Yelp Fusion API" icon="yelp" href="https://docs.developer.yelp.com/" />

  <Card title="Personas" icon="user" href="/features/personas" />

  <Card title="Focus Groups" icon="users" href="/features/focus-groups" />

  <Card title="Mave Agent" icon="brain" href="/features/mave-agent" />

  <Card title="Chat" icon="message" href="/features/chat" />
</CardGroup>