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

# Market Data

> Market trends, density, leaders, opportunity, and valuation intelligence.

Market endpoints return collected market intelligence for the authenticated account or requested city/category segment. Public API endpoints use API keys. Dashboard endpoints use the signed-in app session.

## GET /api/v1/market

Returns stored market trend rows and summary stats for the caller's active business context.

Required scope: `analytics:read`. Requires Growth or higher.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://app.neariq.io/api/v1/market?period=last_30_days&limit=20" \
    -H "X-NearIQ-Key: niq_your_key_here"
  ```
</RequestExample>

```json theme={null}
{
  "trends": [
    {
      "keyword": "personal training",
      "category": "service",
      "mention_count": 18,
      "competitor_count": 3,
      "trend": "rising"
    }
  ],
  "stats": {
    "city": "Dallas",
    "category": "gym",
    "totalBusinesses": 42,
    "avgRating": 4.4,
    "avgReviewCount": 188
  },
  "_receipt": {
    "source": "stored",
    "charged": false
  }
}
```

## GET /api/v1/market/trends

Returns collected trend topics for a city/category segment, plus current market summary and review-velocity movement. This endpoint reads stored market data only.

Required scope: `analytics:read`. Requires Growth or higher.

<ParamField header="X-NearIQ-Key" type="string" required>
  Your API key from Settings > API Keys.
</ParamField>

<ParamField query="city" type="string" required>
  City name, for example `Dallas`.
</ParamField>

<ParamField query="category" type="string">
  Category key, for example `gym`. Omit to use all collected categories for the city.
</ParamField>

<ParamField query="period" type="string" default="last_90_days">
  `last_30_days`, `last_90_days`, or `last_180_days`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://app.neariq.io/api/v1/market/trends?city=Dallas&category=gym&period=last_90_days" \
    -H "X-NearIQ-Key: niq_your_key_here"
  ```
</RequestExample>

```json theme={null}
{
  "segment": { "city": "Dallas", "category": "gym", "country": "US" },
  "period": "last_90_days",
  "summary": {
    "totalBusinesses": 42,
    "avgRating": 4.4,
    "medianRating": 4.5,
    "avgReviewCount": 188,
    "avgHealthScore": 76,
    "avgVelocity7d": 3.1
  },
  "trends": [
    {
      "keyword": "personal training",
      "category": "service",
      "mentionCount": 18,
      "competitorCount": 3,
      "avgSentiment": 0.7,
      "inOwnReviews": false,
      "isGap": true,
      "trend": "rising"
    }
  ]
}
```

Trend categories are normalized at read time so service, product, market-gap, and general topic filters remain consistent even when older rows used broader category labels.

## GET /api/businesses/me/trends

Returns Market tab trends for the signed-in app user. The dashboard supports these filters:

| Filter        | Meaning                                                               |
| ------------- | --------------------------------------------------------------------- |
| `all`         | All visible trend keywords.                                           |
| `gaps`        | Keywords found in competitor feedback but not your own reviews.       |
| `trending_up` | Keywords with rising mentions.                                        |
| `services`    | Service-focused terms such as classes, appointments, or coaching.     |
| `products`    | Product-focused terms such as memberships, packages, or retail items. |

## GET /api/v1/market/leaders

Returns current market leaders for a city/category segment.

Required scope: `analytics:read`. Requires Growth or higher.

<ParamField query="sort" type="string" default="rating">
  `rating` or `reviews`.
</ParamField>

## GET /api/v1/market/density

Returns collected market density around a latitude/longitude center, including market saturation, average rating, average review count, and velocity distribution.

Leader and density rows include `businessStatus` when NearIQ has detected whether a listing is operational, temporarily closed, or permanently closed.

## GET /api/v1/market/projections

Returns stored rating and review-count crossover projections for tracked competitors.

Required scope: `analytics:read`. Requires Growth or higher.

<ParamField query="metric" type="string" default="all">
  `rating`, `review_count`, or `all`.
</ParamField>

<ParamField query="lookbackDays" type="number" default="180">
  Snapshot lookback window from 30 to 730 days.
</ParamField>

<ParamField query="limit" type="number" default="50">
  Maximum projected competitors to return. Maximum `100`.
</ParamField>

```bash theme={null}
curl "https://app.neariq.io/api/v1/market/projections?metric=all&lookbackDays=180" \
  -H "X-NearIQ-Key: niq_your_key_here"
```

```json theme={null}
{
  "business": {
    "id": "biz_123",
    "name": "Aster Grove Fitness"
  },
  "projections": [
    {
      "competitorId": "comp_xyz",
      "metric": "review_count",
      "status": "projected_overtake",
      "currentGap": 42,
      "daysToCrossover": 58
    }
  ],
  "_receipt": {
    "source": "stored",
    "charged": false
  }
}
```

## GET /api/v1/market/saturation

Returns saturation for a city/category segment. Saturation is a directional index for comparing crowded and under-covered segments; it is not a live traffic estimate.

## GET /api/v1/market/signals

Returns actionable market signals such as fast-growing competitors, response gaps, topic gaps, crowded segments, and review moat leaders.

## GET /api/market/leaderboard

Returns app-session leaderboard rows for a city and category. The endpoint supports pagination through `limit` and `offset`.

```json theme={null}
{
  "businesses": [
    {
      "rank": 1,
      "place_id": "ChIJ...",
      "name": "Example Fitness",
      "category": "gym",
      "city": "Dallas",
      "rating": 4.8,
      "review_count": 421,
      "health_score": 88,
      "velocity_7d": 9
    }
  ],
  "total": 200,
  "offset": 0,
  "limit": 50,
  "filters": { "city": "Dallas", "category": "gym", "country": "US", "sort": "rating" }
}
```

## GET /api/market/valuation

Returns valuation intelligence for the signed-in account's tracked competitors. Scores and revenue estimates are directional public-signal estimates, not financial advice or formal appraisals.

```json theme={null}
{
  "ownBusiness": {
    "name": "My Business",
    "valuation": { "score": 68, "tier": "strong" },
    "revenueEstimate": { "annualLow": 420000, "annualMid": 680000, "annualHigh": 940000 }
  },
  "competitors": [
    {
      "competitorId": "comp_123",
      "name": "Example Fitness",
      "rating": 4.7,
      "reviewCount": 360,
      "valuation": { "score": 72, "tier": "strong" },
      "revenueEstimate": { "annualLow": 520000, "annualMid": 760000, "annualHigh": 1100000 }
    }
  ],
  "marketContext": {
    "city": "Dallas",
    "category": "gym",
    "avgRating": 4.4,
    "avgReviewCount": 188,
    "totalBusinesses": 42
  }
}
```

## GET /api/market/opportunity

Dashboard endpoint for Growth+ market-entry analysis. It compares collected city/category rows and returns opportunity scoring for franchise expansion, acquisition scouting, and market entry decisions.

```bash theme={null}
curl "https://app.neariq.io/api/market/opportunity?city=Dallas&category=gym&radius=5" \
  -b "session cookie"
```

```json theme={null}
{
  "city": "Dallas",
  "category": "gym",
  "radiusMiles": 5,
  "opportunityScore": 76,
  "summary": {
    "marketSize": 42,
    "avgRating": 4.4,
    "avgReviewCount": 188
  },
  "recommendations": [
    "Target neighborhoods with high demand and low review depth."
  ]
}
```

## GET /api/market/stats

Dashboard endpoint that returns aggregate market cards for a city/category segment.

```bash theme={null}
curl "https://app.neariq.io/api/market/stats?city=Dallas&category=gym&country=US" \
  -b "session cookie"
```

```json theme={null}
{
  "totalBusinesses": 42,
  "avgRating": 4.4,
  "avgReviewCount": 188,
  "avgHealthScore": 76,
  "velocity7d": 3.1
}
```

## GET /api/market/trends-search

Dashboard endpoint for market keyword interest lookup. Use it for broad category research before choosing a tracked segment.

```bash theme={null}
curl "https://app.neariq.io/api/market/trends-search?q=fitness%20classes&range=today%2012-m&geo=US" \
  -b "session cookie"
```

```json theme={null}
{
  "query": "fitness classes",
  "geo": "US",
  "range": "today 12-m",
  "points": [
    { "date": "2026-05-01", "value": 74 }
  ]
}
```

## POST /api/market/seed

Dashboard endpoint that queues a bounded market-data seed for a city/category pair when no recent rows exist. The endpoint is budget-capped and returns existing data status when the segment is already available.

```bash theme={null}
curl -X POST "https://app.neariq.io/api/market/seed" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{ "city": "Dallas", "state": "TX", "category": "gym" }'
```

```json theme={null}
{
  "status": "queued",
  "city": "Dallas",
  "category": "gym",
  "estimatedRows": 100
}
```

## Market endpoint errors

| Status | Meaning                                                     |
| ------ | ----------------------------------------------------------- |
| `400`  | Missing city/category, invalid metric, or unsupported range |
| `401`  | Missing dashboard session or API key                        |
| `403`  | Plan or API scope does not allow market intelligence        |
| `404`  | No active business or stored market segment found           |
| `429`  | Market seed budget reached                                  |
| `500`  | Stored market data could not be loaded                      |