Market Data

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.

curl "https://app.neariq.io/api/v1/market?period=last_30_days&limit=20" \
  -H "X-NearIQ-Key: niq_your_key_here"

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

string

required

Your API key from Settings > API Keys.

string

required

City name, for example Dallas.

string

Category key, for example gym. Omit to use all collected categories for the city.

string

default:"last_90_days"

last_30_days, last_90_days, or last_180_days.

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"

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

string

default:"rating"

rating or reviews.

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.

string

default:"all"

rating, review_count, or all.

number

default:"180"

Snapshot lookback window from 30 to 730 days.

number

default:"50"

Maximum projected competitors to return. Maximum 100.

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

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

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

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

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

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

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

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

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

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

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" }'

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

API Reference

Endpoints

Webhooks

GET /api/v1/market

GET /api/v1/market/trends

GET /api/businesses/me/trends

GET /api/v1/market/leaders

GET /api/v1/market/density

GET /api/v1/market/projections

GET /api/v1/market/saturation

GET /api/v1/market/signals

GET /api/market/leaderboard

GET /api/market/valuation

GET /api/market/opportunity

GET /api/market/stats

GET /api/market/trends-search

POST /api/market/seed

Market endpoint errors

​GET /api/v1/market

​GET /api/v1/market/trends

​GET /api/businesses/me/trends

​GET /api/v1/market/leaders

​GET /api/v1/market/density

​GET /api/v1/market/projections

​GET /api/v1/market/saturation

​GET /api/v1/market/signals

​GET /api/market/leaderboard

​GET /api/market/valuation

​GET /api/market/opportunity

​GET /api/market/stats

​GET /api/market/trends-search

​POST /api/market/seed

​Market endpoint errors

GET /api/v1/market

GET /api/v1/market/trends

GET /api/businesses/me/trends

GET /api/v1/market/leaders

GET /api/v1/market/density

GET /api/v1/market/projections

GET /api/v1/market/saturation

GET /api/v1/market/signals

GET /api/market/leaderboard

GET /api/market/valuation

GET /api/market/opportunity

GET /api/market/stats

GET /api/market/trends-search

POST /api/market/seed

Market endpoint errors