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 /me/competitors

Returns all competitors you are currently tracking. 
curl https://app.neariq.io/api/v1/me/competitors \
  -H "X-NearIQ-Key: niq_your_key_here"

{
  "competitors": [
    {
      "id": "comp_xyz",
      "name": "Rival Pizza",
      "address": "456 Broadway, New York, NY",
      "rating": 4.3,
      "reviewCount": 189,
      "distanceKm": 0.8,
      "placeId": "ChIJ...",
      "isOpen": true
    }
  ],
  "total": 5
}

​
GET /competitors/:id

Fetch a single competitor by ID. 
curl https://app.neariq.io/api/v1/competitors/comp_xyz \
  -H "X-NearIQ-Key: niq_your_key_here"

​
GET /competitors/:id/snapshots

Daily rating history for a specific competitor. 
curl "https://app.neariq.io/api/v1/competitors/comp_xyz/snapshots?days=30" \
  -H "X-NearIQ-Key: niq_your_key_here"

​
GET /competitors/:id/reviews

Paginated reviews for a specific competitor. 
curl "https://app.neariq.io/api/v1/competitors/comp_xyz/reviews?limit=20" \
  -H "X-NearIQ-Key: niq_your_key_here"
Review text is refreshed when available. If text is being refreshed, text is null and reviewTextStatus is loading; rating, author, date, and other metadata remain available. 
{
  "reviews": [
    {
      "rating": 4,
      "text": null,
      "author": "A Google user",
      "publishedAt": "2026-04-18T06:00:00Z",
      "ownerResponse": null,
      "reviewTextStatus": "loading"
    }
  ]
}

​
POST /api/competitors/import

Authenticated dashboard endpoint for bulk importing competitors from CSV rows or Google Maps URLs. 
curl https://app.neariq.io/api/competitors/import \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{"type":"csv","data":"name,address,city,state\nRival Pizza,456 Broadway,New York,NY"}'
The endpoint enforces the active user or organization competitor limit, skips duplicates, rate-limits Google Places lookups, and returns row-level errors. 
{
  "imported": 1,
  "skipped": 0,
  "errors": []
}

​
GET /api/competitors

Authenticated dashboard endpoint for tracked competitors. When secondary platform data is available, each competitor includes a platform_ratings object. 
{
  "competitors": [
    {
      "id": "comp_xyz",
      "name": "Rival Pizza",
      "rating": 4.3,
      "review_count": 189,
      "platform_ratings": {
        "tripadvisor_rating": 4.0,
        "tripadvisor_review_count": 42,
        "tripadvisor_url": "https://www.tripadvisor.com/...",
        "yelp_rating": null,
        "yelp_review_count": null
      }
    }
  ]
}

​
GET /api/competitors/:id/ads

Authenticated dashboard endpoint for Agency+ accounts. Returns stored Meta Ad Library archive rows collected by the weekly worker. 
curl https://app.neariq.io/api/competitors/comp_xyz/ads \
  -b "session cookie"

{
  "competitor": {
    "id": "comp_xyz",
    "name": "Rival Pizza",
    "metaAdMonitoringEnabled": true,
    "lastMetaAdCheck": "2026-05-05T09:30:00Z"
  },
  "ads": [
    {
      "ad_id": "1234567890",
      "page_name": "Rival Pizza",
      "ad_creative_url": "https://www.facebook.com/ads/library/...",
      "ad_body": "Order online today.",
      "ad_status": "ACTIVE",
      "publisher_platforms": ["facebook", "instagram"],
      "detected_at": "2026-05-05T09:30:00Z",
      "last_seen_at": "2026-05-05T09:30:00Z"
    }
  ],
  "stats": {
    "total": 1,
    "active": 1,
    "platforms": ["facebook", "instagram"],
    "lastSeenAt": "2026-05-05T09:30:00Z"
  }
}
The worker uses META_AD_LIBRARY_ACCESS_TOKEN when present and can fall back to FACEBOOK_APP_ID|FACEBOOK_APP_SECRET. Meta API coverage varies by country and ad category, so this endpoint exposes only archive rows returned by Meta.