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

# Leaderboard

> Access market leaderboard rows and dashboard aggregate leaderboard statistics.

Use leaderboard endpoints to compare businesses in a city, category, or market segment.

## GET /api/v1/leaderboard

Returns collected market businesses for API integrations. This endpoint reads stored market data only and does not start live collection.

Required scope: `competitors:read`.

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

<ParamField query="city" type="string">
  Optional city filter.
</ParamField>

<ParamField query="category" type="string">
  Optional business category filter.
</ParamField>

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

<ParamField query="order" type="string" default="desc">
  `asc` or `desc`.
</ParamField>

<ParamField query="limit" type="number" default="50">
  Number of rows to return. Maximum `100`.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Pagination offset.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://app.neariq.io/api/v1/leaderboard?city=Dallas&category=gym&sort=review_count&limit=20" \
    -H "X-NearIQ-Key: niq_your_key_here"
  ```
</RequestExample>

```json theme={null}
{
  "businesses": [
    {
      "place_id": "ChIJ...",
      "name": "Example Fitness",
      "category": "Gym",
      "city": "Dallas",
      "state": "TX",
      "address": "100 Main St, Dallas, TX",
      "rating": 4.8,
      "review_count": 421,
      "owner_response_rate": 0.66,
      "last_refreshed_at": "2026-05-19T12:00:00.000Z"
    }
  ]
}
```

## GET /api/leaderboard

Returns the dashboard leaderboard with pagination, filter breakdowns, and aggregate market intelligence cards. This endpoint uses the signed-in app session.

```bash theme={null}
curl "https://app.neariq.io/api/leaderboard?city=Dallas&category=gym&sortBy=health_score&limit=50&offset=0"
```

```json theme={null}
{
  "results": [
    {
      "rank": 1,
      "place_id": "ChIJ...",
      "name": "Example Fitness",
      "category": "gym",
      "rating": 4.8,
      "review_count": 421,
      "health_score": 88,
      "velocity_7d": 9
    }
  ],
  "total": 200,
  "offset": 0,
  "limit": 50,
  "stats": {
    "avg_rating": 4.42,
    "median_rating": 4.5,
    "avg_health": 77,
    "median_health": 76,
    "avg_review_count": 188,
    "total_businesses": 200,
    "estimated_annual_revenue": 82000000,
    "estimated_annual_revenue_low": 52000000,
    "estimated_annual_revenue_high": 124000000,
    "revenue_estimate_count": 200,
    "avg_valuation_score": 64,
    "valuation_estimate_count": 200,
    "premium_count": 18,
    "distressed_count": 9
  },
  "geo_breakdown": [{ "label": "TX", "count": 200 }],
  "category_breakdown": null,
  "city_breakdown": [{ "label": "Dallas", "count": 200 }]
}
```

Revenue fields are directional estimates from public market signals. The dashboard converts revenue plus valuation intelligence into estimated business value dollar ranges for user-facing cards. These values are not financial appraisals and should be used for prioritization, comparison, and trend monitoring.

### Response fields

| Field                      | Description                                                                                            |
| -------------------------- | ------------------------------------------------------------------------------------------------------ |
| `health_score`             | 0-100 directional competitive strength score.                                                          |
| `velocity_7d`              | Recent review-growth velocity when available.                                                          |
| `estimated_annual_revenue` | Midpoint directional market revenue estimate for rows with enough public signals.                      |
| `avg_valuation_score`      | Internal average 0-100 valuation intelligence score used to derive dashboard business value estimates. |
| `premium_count`            | Number of businesses with high valuation intelligence in the current result set.                       |
| `distressed_count`         | Number of businesses with weak valuation intelligence in the current result set.                       |