Skip to main content

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.

Scenario

What’s trending in your local market? New açaí bowl shops opening? Bubble tea exploding? You search Yelp for recently opened businesses in trending categories, analyze their ratings and review velocity, then use Mave to identify consumer trends and predict where the market is heading. Flow: Yelp GET /businesses/search (multiple trending categories) → Compare: new business counts, ratings, review velocity → Mavera POST /mave/chat → Consumer trend report

Code

import os, requests, time

YELP = os.environ["YELP_API_KEY"]
MV = os.environ["MAVERA_API_KEY"]
YELP_H = {"Authorization": f"Bearer {YELP}"}
MV_H = {"Authorization": f"Bearer {MV}", "Content-Type": "application/json"}

LOCATION = "Austin, TX"
CATEGORIES = [
    "bubbletea", "acaibowls", "juicebars", "poke",
    "korean", "ramen", "mediterranean", "vegan",
    "coffee", "cocktailbars", "breweries", "wine_bars",
]

# 1. Search each category
category_data = []
for cat in CATEGORIES:
    r = requests.get(f"https://api.yelp.com/v3/businesses/search",
        headers=YELP_H,
        params={"categories": cat, "location": LOCATION, "limit": 50, "sort_by": "review_count"})
    if r.status_code == 429:
        time.sleep(2)
        continue
    r.raise_for_status()
    bizes = r.json().get("businesses", [])
    total = r.json().get("total", 0)

    if not bizes:
        continue

    avg_rating = sum(b.get("rating", 0) for b in bizes) / len(bizes)
    avg_reviews = sum(b.get("review_count", 0) for b in bizes) / len(bizes)
    high_rated = sum(1 for b in bizes if b.get("rating", 0) >= 4.5)
    price_dist = {}
    for b in bizes:
        p = b.get("price", "N/A")
        price_dist[p] = price_dist.get(p, 0) + 1

    category_data.append({
        "category": cat,
        "total_in_area": total,
        "sampled": len(bizes),
        "avg_rating": round(avg_rating, 1),
        "avg_review_count": round(avg_reviews),
        "high_rated_pct": round(high_rated / len(bizes) * 100) if bizes else 0,
        "price_distribution": price_dist,
        "top_3": [b["name"] for b in sorted(bizes, key=lambda x: -x.get("review_count", 0))[:3]],
    })
    time.sleep(0.5)

# 2. Mave trend analysis
cat_block = "\n".join(
    f"- {d['category']}: {d['total_in_area']} total, avg {d['avg_rating']}/5, "
    f"avg {d['avg_review_count']} reviews, {d['high_rated_pct']}% rated 4.5+. "
    f"Top: {', '.join(d['top_3'])}"
    for d in sorted(category_data, key=lambda x: -x["total_in_area"])
)

analysis = requests.post("https://app.mavera.io/api/v1/mave/chat",
    headers=MV_H,
    json={"message": f"""Analyze category trends in {LOCATION} from Yelp data.

{cat_block}

Produce:
1. Emerging trends (categories with high ratings but low total count — growth signal)
2. Saturated categories (high count, declining quality — mature market)
3. Consumer behavior shifts (what do category patterns tell us about local preferences?)
4. Investment opportunities (where should a new business or product launch?)
5. Seasonal or demographic factors driving these trends"""}).json()

print(f"=== Category Trends in {LOCATION} ===")
print(analysis.get("content", "")[:1500])

Example Output

=== Category Trends in Austin, TX ===

## Emerging Trends (high quality, low count — growth phase)
- **Poke** (23 total, avg 4.4/5, 78% rated 4.5+): Strong quality signal.
  Early movers doing well. Room for 10+ more locations.
- **Korean** (31 total, avg 4.3/5): Korean BBQ and fried chicken
  trending with younger demographics. K-culture tailwind.

## Saturated Categories
- **Coffee** (183 total, avg 4.0/5): Mature. New entrants need strong
  differentiation. Quality declining as volume increases.
- **Cocktail bars** (120 total, avg 3.9/5): Oversupplied. Average
  ratings declining — sign of a mature market.

## Consumer Behavior Shifts
- Health-forward categories (acai, juice bars, poke) growing fastest
- Asian fusion (Korean, ramen, poke) replacing traditional American
- Bubble tea velocity suggests Gen Z influence on market

## Investment Opportunities
1. Korean fried chicken (high demand, few operators)
2. Poke + açaí combo concept (health-forward, underserved in South Austin)
3. Vegan cocktail bar (two trends in one, zero operators)

Error Handling

Yelp uses specific category aliases (e.g., bubbletea not bubble_tea). Find valid aliases at Yelp Category List.
The total field in search results may be large, but you can only paginate to 1,000 results. Use total for market size, sampled for analysis.