Leaderboard

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.

string

required

Your API key from Settings > API Keys.

string

Optional city filter.

string

Optional business category filter.

string

default:"rating"

rating or review_count.

string

default:"desc"

asc or desc.

number

default:"50"

Number of rows to return. Maximum 100.

number

default:"0"

Pagination offset.

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"

{
  "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.

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

{
  "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.

API Reference

Endpoints

Webhooks

GET /api/v1/leaderboard

GET /api/leaderboard

Response fields

​GET /api/v1/leaderboard

​GET /api/leaderboard

​Response fields

GET /api/v1/leaderboard

GET /api/leaderboard

Response fields