Skip to main content
GET
/
behavioral-signals
curl "https://app.neariq.io/api/v1/behavioral-signals" \
  -H "X-NearIQ-Key: niq_your_key_here"
GET /api/v1/behavioral-signals returns raw stored facts for the active business’s engagement and listing activity compared with tracked competitors. Generated grades, percentiles, scores, and recommendations remain dashboard-only. This endpoint is available on Growth plans and higher. Use an API key with the analytics:read scope.
​
X-NearIQ-Key
string
required
Your API key from Settings > API Keys
curl "https://app.neariq.io/api/v1/behavioral-signals" \
  -H "X-NearIQ-Key: niq_your_key_here"

​
Response

{
  "connected": true,
  "businessId": "uuid",
  "businessName": "NearIQ Demo Fitness",
  "signals": {
    "reviewResponseRate": {
      "value": 45,
      "displayValue": "45%",
      "unit": "%",
      "benchmark": 72,
      "benchmarkDisplay": "72%",
      "trend": "stable",
      "higherIsBetter": true
    },
    "reviewResponseTime": {
      "value": 48,
      "displayValue": "48h",
      "unit": "hours",
      "benchmark": 12,
      "benchmarkDisplay": "12h",
      "trend": "unknown",
      "higherIsBetter": false
    }
  },
  "competitorComparison": [
    {
      "id": "uuid",
      "name": "NearIQ Demo Fitness",
      "isYou": true,
      "metrics": {
        "reviewResponseRate": 45,
        "reviewResponseTimeHours": 48,
        "reviewVelocityMonthly": 3.2,
        "photoCount": 42,
        "postFrequencyMonthly": null,
        "reviewRecencyDays": 8
      }
    }
  ],
  "dataCoverage": {
    "competitors": 4,
    "reviews": true,
    "snapshots": true,
    "listing": true,
    "posts": false
  }
}

​
Signals

Signals include values, display text, stored benchmarks, trends, units, and whether a higher value is better. The competitor comparison table returns raw metric values for each row so API consumers can apply their own scoring model.
SignalMeaning
reviewResponseRatePercent of visible reviews with an owner reply.
reviewResponseTimeAverage time between review publication and owner reply. Uses cached competitor_reviews_cache.avg_response_hours when available, then falls back to stored review timestamps.
reviewVelocityEstimated new reviews per month from snapshots or cached review dates.
photoCountListing photo count when available from cached listing data.
postFrequencyMonthly listing post activity when collected.
reviewRecencyDays since the newest visible review. Lower is better.

​
Access

The endpoint uses the caller’s active personal or organization business context. Organization members only receive data for businesses they can access. Accounts below Growth receive 403. API keys without analytics:read receive 403 requiredScope.