Skip to main content

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.

GET /api/v1/behavioral-signals returns the active business’s engagement health compared with tracked competitors. This endpoint is available on Growth plans and higher. Use an API key with the competitors:read scope.

​
Response

{
  "connected": true,
  "businessId": "uuid",
  "businessName": "Riverside Fitness",
  "overallGrade": "C",
  "overallScore": 58,
  "signals": {
    "reviewResponseRate": {
      "value": 45,
      "displayValue": "45%",
      "unit": "%",
      "benchmark": 72,
      "benchmarkDisplay": "72%",
      "percentile": 25,
      "trend": "stable",
      "grade": "D",
      "score": 25,
      "higherIsBetter": true
    },
    "reviewResponseTime": {
      "value": 48,
      "displayValue": "48h",
      "unit": "hours",
      "benchmark": 12,
      "benchmarkDisplay": "12h",
      "percentile": 30,
      "trend": "unknown",
      "grade": "D",
      "score": 30,
      "higherIsBetter": false
    }
  },
  "competitorComparison": [
    { "id": "uuid", "name": "Riverside Fitness", "isYou": true, "score": 58, "grade": "C" },
    { "id": "uuid", "name": "Metro Strength", "isYou": false, "score": 72, "grade": "B" }
  ],
  "recommendations": [
    {
      "priority": 1,
      "action": "Reply to 12 unanswered reviews",
      "impact": "high",
      "effort": "36 minutes",
      "detail": "You are at 45%; the tracked competitor benchmark is 72%."
    }
  ],
  "dataCoverage": {
    "competitors": 4,
    "reviews": true,
    "snapshots": true,
    "listing": true,
    "posts": false
  }
}

​
Signals

overallScore is the average of signal scores that have enough comparable data. Signals with score: null are excluded from the overall score and grade. The competitor comparison table also excludes the entity being scored from its peer benchmark so “you vs. competitors” is not self-referential.
SignalMeaning
reviewResponseRatePercent of visible reviews with an owner reply.
reviewResponseTimeAverage time between review publication and owner reply when exact timestamps are available.
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. Excluded from scoring when unavailable.
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 competitors:read receive 403 requiredScope.