Skip to main content
GET
/
v1
/
market
curl "https://app.neariq.io/api/v1/market?period=last_30_days&limit=20" \
  -H "X-NearIQ-Key: niq_your_key_here"
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.
​
X-NearIQ-Key
string
required
Your API key from Settings > API Keys.
​
city
string
required
City name, for example Dallas.
​
category
string
Category key, for example gym. Omit to use all collected categories for the city.
​
period
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:
FilterMeaning
allAll visible trend keywords.
gapsKeywords found in competitor feedback but not your own reviews.
trending_upKeywords with rising mentions.
servicesService-focused terms such as classes, appointments, or coaching.
productsProduct-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.
​
sort
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.
​
metric
string
default:"all"
rating, review_count, or all.
​
lookbackDays
number
default:"180"
Snapshot lookback window from 30 to 730 days.
​
limit
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
}
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

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