Skip to main content
The competitor endpoints give you detailed access to each business you track. You can retrieve a competitor’s full Google Business Profile data, their historical rating trajectory, and their cached Google reviews with metadata. All competitor endpoints enforce ownership — you can only access competitors that belong to your NearIQ account. Requests for competitors owned by another account return 404.

​
GET /api/v1/competitors/:id

Returns full details for a single tracked competitor. 
curl https://neariq.io/api/v1/competitors/comp_abc123 \
  -H "X-NearIQ-Key: niq_live_..."

​
Path parameters

​
id
string
required
The competitor’s unique NearIQ ID. Retrieve this from GET /api/v1/me/competitors.

​
Response fields

​
id
string
required
Unique competitor ID.
​
name
string
required
Competitor business name.
​
placeId
string
Google Maps Place ID.
​
address
string
Street address.
​
category
string
Google Business category.
​
website
string
Website URL.
​
phone
string
Phone number.
​
rating
number
Current Google rating (1.0–5.0).
​
reviewCount
number
Total number of Google reviews.
​
healthScore
number
NearIQ profile completeness score (0–100).
​
status
string
Google listing status. Common values: OPERATIONAL, CLOSED_TEMPORARILY, CLOSED_PERMANENTLY.
​
lastCheckedAt
string
ISO 8601 timestamp of the most recent NearIQ data check.
​
trackedSince
string
required
ISO 8601 timestamp of when you added this competitor to NearIQ.

​
GET /api/v1/competitors/:id/snapshots

Returns historical rating and review-count snapshots for a competitor. Each snapshot is a point-in-time data capture by NearIQ. Snapshots are returned in reverse-chronological order. 
curl "https://neariq.io/api/v1/competitors/comp_abc123/snapshots?limit=30&from=2025-01-01" \
  -H "X-NearIQ-Key: niq_live_..."

​
Path parameters

​
id
string
required
The competitor’s unique NearIQ ID.

​
Query parameters

​
limit
number
default:"90"
Number of most-recent snapshots to return. Maximum is 365.
​
from
string
Inclusive start date filter. ISO date string (e.g., 2025-01-01).
​
to
string
Inclusive end date filter. ISO date string (e.g., 2025-06-30).

​
Response fields

​
competitor
object
required
​
count
number
required
Number of snapshots returned.
​
snapshots
object[]
required

​
GET /api/v1/competitors/:id/reviews

Returns cached Google reviews for a competitor along with aggregated metadata. Reviews are served from NearIQ’s cache (up to 200 reviews per competitor). 
curl "https://neariq.io/api/v1/competitors/comp_abc123/reviews?sort=lowest&limit=25" \
  -H "X-NearIQ-Key: niq_live_..."

​
Path parameters

​
id
string
required
The competitor’s unique NearIQ ID.

​
Query parameters

​
limit
number
default:"50"
Number of reviews to return. Maximum is 200.
​
sort
string
default:"newest"
Sort order. One of newest, oldest, highest, or lowest.

​
Response fields

​
competitor
object
required
​
meta
object
required
​
reviews
object[]
required