Competitors

Returns all competitors you are currently tracking with raw stored facts such as ratings, review counts, listing details, latest check timing, and closure flags. Generated health, momentum, financial, valuation, and revenue intelligence remains dashboard-only.

string

required

Your API key from Settings > API Keys

curl https://app.neariq.io/api/v1/me/competitors \
  -H "X-NearIQ-Key: niq_your_key_here"

GET /api/v1/competitors is an alias for GET /api/v1/me/competitors so automation tools such as Zapier can use the simpler resource URL.

const neariq = new NearIQ({ apiKey: 'niq_your_key_here' })
const { competitors } = await neariq.competitors.list()

{
  "competitors": [
    {
      "id": "comp_xyz",
      "name": "Rival Pizza",
      "address": "456 Broadway, New York, NY",
      "rating": 4.3,
      "reviewCount": 189,
      "permanentlyClosed": false,
      "closedDetectedAt": null,
      "placeId": "ChIJ...",
      "lastCheckedAt": "2026-05-06T14:10:00Z"
    }
  ],
  "count": 5
}

permanentlyClosed is true when the latest collected listing status reports the competitor as permanently closed. closedDetectedAt records when NearIQ first detected that status for the tracked competitor.

POST /competitors

Add a competitor to the active business. This endpoint is intended for automation tools, Zapier actions, and custom CRM workflows that discover a business outside NearIQ and need to start tracking it. Requires the competitors:write scope and the account’s remaining competitor quota. Duplicates are rejected when the same place_id is already active; inactive duplicates are reactivated.

curl https://app.neariq.io/api/v1/competitors \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-NearIQ-Key: niq_your_key_here" \
  -d '{
    "name": "Rival Pizza",
    "place_id": "ChIJ...",
    "address": "456 Broadway, New York, NY",
    "rating": 4.3,
    "review_count": 189,
    "website_url": "https://example.com"
  }'

{
  "competitor": {
    "id": "comp_xyz",
    "name": "Rival Pizza",
    "placeId": "ChIJ...",
    "address": "456 Broadway, New York, NY",
    "website": "https://example.com",
    "rating": 4.3,
    "reviewCount": 189,
    "createdAt": "2026-05-20T16:30:00Z",
    "reactivated": false
  }
}

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"

The detail response includes the same raw stored facts and closure fields as the list endpoint. Generated scoring and classification fields are not returned by public v1 competitor endpoints. Use include to request stored competitor detail sections without triggering provider lookups:

curl "https://app.neariq.io/api/v1/competitors/comp_xyz?include=all" \
  -H "X-NearIQ-Key: niq_your_key_here"

include accepts snapshot, reviews, products, hiring, ads, and tech_stack; use include=all for every stored section. reviews requires the reviews:read scope. snapshot, products, hiring, ads, and tech_stack require analytics:read. These sections are stored data only: latest collected snapshot fields, cached review metadata, detected products and services, hiring rows, ad rows, and tech stack rows.

{
  "id": "comp_xyz",
  "name": "Rival Pizza",
  "placeId": "ChIJ...",
  "included": ["snapshot", "reviews", "products", "hiring", "ads", "tech_stack"],
  "latestSnapshot": {
    "checkedAt": "2026-05-08T14:10:00Z",
    "rating": 4.3,
    "reviewCount": 189,
    "localPackRank": 3,
    "isRunningAds": true
  },
  "reviewMeta": {
    "cachedAt": "2026-05-08T14:10:00Z",
    "ownerResponseRate": 0.62,
    "platformRatings": {
      "yelp": { "rating": 4.1, "reviewCount": 42 },
      "tripadvisor": { "rating": null, "reviewCount": null }
    }
  },
  "products": [
    { "productName": "Lunch special", "price": 12, "currency": "USD", "category": "menu" }
  ],
  "hiring": {
    "summary": { "active": 2, "lastJobCheck": "2026-05-08T14:10:00Z" },
    "jobs": []
  },
  "ads": {
    "summary": { "active": 1, "platforms": ["facebook"] },
    "ads": []
  },
  "techStack": [
    { "toolName": "Toast", "category": "pos", "confidence": 0.9 }
  ]
}

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 ad archive rows collected by the weekly refresh.

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"
  }
}

Ad activity coverage varies by country and ad category. This endpoint exposes only stored ad rows already collected for the account.

GET /api/competitors/:id/enrich

Authenticated dashboard endpoint for Growth+ accounts. Returns stored competitor contact enrichment for the active business without starting a new scan.

curl "https://app.neariq.io/api/competitors/comp_xyz/enrich" \
  -b "session cookie"

{
  "competitor": {
    "id": "comp_xyz",
    "name": "Rival Pizza",
    "website": "https://example.com",
    "ownerName": "Jordan Lee",
    "contactEmail": "hello@example.com",
    "phone": "+12125551234",
    "socialLinks": [{ "platform": "instagram", "url": "https://example.com/profile" }],
    "enrichmentStatus": "ready",
    "enrichedAt": "2026-05-30T18:00:00.000Z"
  }
}

POST /api/competitors/:id/enrich

Starts a bounded Growth+ enrichment scan for the competitor’s public website and stores the resulting contact fields.

curl -X POST "https://app.neariq.io/api/competitors/comp_xyz/enrich" \
  -b "session cookie"

{
  "ok": true,
  "status": "ready",
  "competitor": {
    "id": "comp_xyz",
    "ownerName": "Jordan Lee",
    "contactEmail": "hello@example.com"
  }
}

GET /api/competitors/:id/photos

Returns stored photo metadata for the competitor listing.

curl "https://app.neariq.io/api/competitors/comp_xyz/photos" \
  -b "session cookie"

{
  "photos": [
    {
      "name": "places/photo-ref",
      "url": "https://app.neariq.io/api/photo-proxy?ref=...",
      "width": 1200,
      "height": 800,
      "capturedAt": "2026-05-30T18:00:00.000Z"
    }
  ]
}

GET /api/competitors/:id/products

Returns detected products, services, menu items, packages, and prices for the selected competitor.

curl "https://app.neariq.io/api/competitors/comp_xyz/products" \
  -b "session cookie"

{
  "products": [
    {
      "productName": "Lunch special",
      "category": "menu",
      "price": 12,
      "currency": "USD",
      "source": "listing",
      "detectedAt": "2026-05-30T18:00:00.000Z"
    }
  ]
}

GET /api/competitors/:id/tech-stack

Returns stored technology and vendor signals for a Growth+ account.

curl "https://app.neariq.io/api/competitors/comp_xyz/tech-stack" \
  -b "session cookie"

{
  "techStack": [
    {
      "toolName": "Reservation tool",
      "category": "booking",
      "confidence": 0.82,
      "detectedAt": "2026-05-30T18:00:00.000Z"
    }
  ],
  "lastScannedAt": "2026-05-30T18:00:00.000Z"
}

POST /api/competitors/:id/tech-stack

Starts a fresh Growth+ website technology scan for the competitor.

curl -X POST "https://app.neariq.io/api/competitors/comp_xyz/tech-stack" \
  -b "session cookie"

{
  "ok": true,
  "status": "queued"
}

GET /api/competitors/:id/website-changes

Lists detected website title, copy, pricing, offer, and contact changes for a competitor.

curl "https://app.neariq.io/api/competitors/comp_xyz/website-changes" \
  -b "session cookie"

{
  "changes": [
    {
      "id": "chg_123",
      "changeType": "pricing",
      "summary": "New membership offer detected",
      "severity": "medium",
      "detectedAt": "2026-05-30T18:00:00.000Z"
    }
  ]
}

GET /api/competitors/:id/youtube

Returns stored public video-channel signals for the competitor when a channel is detected.

curl "https://app.neariq.io/api/competitors/comp_xyz/youtube" \
  -b "session cookie"

{
  "channel": {
    "title": "Rival Pizza",
    "subscriberCount": 1200,
    "videoCount": 48
  },
  "recentVideos": []
}

Returns stored social presence metrics for the competitor.

curl "https://app.neariq.io/api/competitors/comp_xyz/social-metrics" \
  -b "session cookie"

{
  "metrics": [
    {
      "platform": "instagram",
      "followers": 4200,
      "posts": 188,
      "capturedAt": "2026-05-30T18:00:00.000Z"
    }
  ]
}

GET /api/competitors/:id/platform-ratings

Returns cross-platform rating and review-count rows for the selected competitor.

curl "https://app.neariq.io/api/competitors/comp_xyz/platform-ratings" \
  -b "session cookie"

{
  "ratings": [
    {
      "platform": "google",
      "rating": 4.3,
      "reviewCount": 189,
      "url": "https://example.com/listing"
    }
  ]
}

POST /api/competitors/:id/check

Runs an authenticated on-demand competitor refresh when the account plan and refresh limits allow it.

curl -X POST "https://app.neariq.io/api/competitors/comp_xyz/check" \
  -b "session cookie"

{
  "ok": true,
  "status": "queued",
  "competitorId": "comp_xyz"
}

GET /api/competitors/suggestions

Returns suggested competitors near the active business. Query parameters include radius, category, and limit.

curl "https://app.neariq.io/api/competitors/suggestions?radius=8000&limit=10" \
  -b "session cookie"

{
  "suggestions": [
    {
      "name": "Rival Pizza",
      "address": "456 Broadway, New York, NY",
      "rating": 4.3,
      "reviewCount": 189,
      "distanceMeters": 920
    }
  ]
}

GET /api/competitors/jobs

Returns tracked hiring rows for one competitor or the active competitor set.

curl "https://app.neariq.io/api/competitors/jobs?competitor_id=comp_xyz" \
  -b "session cookie"

{
  "jobs": [
    {
      "title": "General Manager",
      "company": "Rival Pizza",
      "location": "New York, NY",
      "postedAt": "2026-05-30T18:00:00.000Z"
    }
  ]
}

PATCH /api/competitors/jobs

Toggles job monitoring for a competitor.

curl -X PATCH "https://app.neariq.io/api/competitors/jobs" \
  -H "Content-Type: application/json" \
  -b "session cookie" \
  -d '{ "competitorId": "comp_xyz", "enabled": true }'

{
  "ok": true,
  "jobMonitoringEnabled": true
}

Dashboard competitor endpoint errors

Status	Meaning
`400`	Invalid ID, missing body fields, or unsupported query values
`401`	Missing dashboard session
`403`	Plan or organization permission does not allow the requested action
`404`	Competitor or active business not found
`429`	On-demand refresh or scan limit reached
`500`	Stored data could not be loaded

API Reference

Endpoints

Webhooks

POST /competitors

GET /competitors/:id

GET /competitors/:id/snapshots

GET /competitors/:id/reviews

POST /api/competitors/import

GET /api/competitors

GET /api/competitors/:id/ads

GET /api/competitors/:id/enrich

POST /api/competitors/:id/enrich

GET /api/competitors/:id/photos

GET /api/competitors/:id/products

GET /api/competitors/:id/tech-stack

POST /api/competitors/:id/tech-stack

GET /api/competitors/:id/website-changes

GET /api/competitors/:id/youtube

GET /api/competitors/:id/platform-ratings

POST /api/competitors/:id/check

GET /api/competitors/suggestions

GET /api/competitors/jobs

PATCH /api/competitors/jobs

Dashboard competitor endpoint errors

​POST /competitors

​GET /competitors/:id

​GET /competitors/:id/snapshots

​GET /competitors/:id/reviews

​POST /api/competitors/import

​GET /api/competitors

​GET /api/competitors/:id/ads

​GET /api/competitors/:id/enrich

​POST /api/competitors/:id/enrich

​GET /api/competitors/:id/photos

​GET /api/competitors/:id/products

​GET /api/competitors/:id/tech-stack

​POST /api/competitors/:id/tech-stack

​GET /api/competitors/:id/website-changes

​GET /api/competitors/:id/youtube

​GET /api/competitors/:id/social-metrics

​GET /api/competitors/:id/platform-ratings

​POST /api/competitors/:id/check

​GET /api/competitors/suggestions

​GET /api/competitors/jobs

​PATCH /api/competitors/jobs

​Dashboard competitor endpoint errors

POST /competitors

GET /competitors/:id

GET /competitors/:id/snapshots

GET /competitors/:id/reviews

POST /api/competitors/import

GET /api/competitors

GET /api/competitors/:id/ads

GET /api/competitors/:id/enrich

POST /api/competitors/:id/enrich

GET /api/competitors/:id/photos

GET /api/competitors/:id/products

GET /api/competitors/:id/tech-stack

POST /api/competitors/:id/tech-stack

GET /api/competitors/:id/website-changes

GET /api/competitors/:id/youtube

GET /api/competitors/:id/social-metrics

GET /api/competitors/:id/platform-ratings

POST /api/competitors/:id/check

GET /api/competitors/suggestions

GET /api/competitors/jobs

PATCH /api/competitors/jobs

Dashboard competitor endpoint errors