> ## 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.

# Competitors

> List, add, and inspect tracked 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.

<ParamField header="X-NearIQ-Key" type="string" required>
  Your API key from Settings > API Keys
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  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.

  ```javascript JavaScript theme={null}
  const neariq = new NearIQ({ apiKey: 'niq_your_key_here' })
  const { competitors } = await neariq.competitors.list()
  ```
</RequestExample>

```json theme={null}
{
  "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.

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "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.

```bash theme={null}
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:

```bash theme={null}
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.

```json theme={null}
{
  "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.

```bash theme={null}
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.

```bash theme={null}
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.

```json theme={null}
{
  "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.

```bash theme={null}
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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```bash theme={null}
curl https://app.neariq.io/api/competitors/comp_xyz/ads \
  -b "session cookie"
```

```json theme={null}
{
  "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.

```bash theme={null}
curl "https://app.neariq.io/api/competitors/comp_xyz/enrich" \
  -b "session cookie"
```

```json theme={null}
{
  "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.

```bash theme={null}
curl -X POST "https://app.neariq.io/api/competitors/comp_xyz/enrich" \
  -b "session cookie"
```

```json theme={null}
{
  "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.

```bash theme={null}
curl "https://app.neariq.io/api/competitors/comp_xyz/photos" \
  -b "session cookie"
```

```json theme={null}
{
  "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.

```bash theme={null}
curl "https://app.neariq.io/api/competitors/comp_xyz/products" \
  -b "session cookie"
```

```json theme={null}
{
  "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.

```bash theme={null}
curl "https://app.neariq.io/api/competitors/comp_xyz/tech-stack" \
  -b "session cookie"
```

```json theme={null}
{
  "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.

```bash theme={null}
curl -X POST "https://app.neariq.io/api/competitors/comp_xyz/tech-stack" \
  -b "session cookie"
```

```json theme={null}
{
  "ok": true,
  "status": "queued"
}
```

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

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

```bash theme={null}
curl "https://app.neariq.io/api/competitors/comp_xyz/website-changes" \
  -b "session cookie"
```

```json theme={null}
{
  "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.

```bash theme={null}
curl "https://app.neariq.io/api/competitors/comp_xyz/youtube" \
  -b "session cookie"
```

```json theme={null}
{
  "channel": {
    "title": "Rival Pizza",
    "subscriberCount": 1200,
    "videoCount": 48
  },
  "recentVideos": []
}
```

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

Returns stored social presence metrics for the competitor.

```bash theme={null}
curl "https://app.neariq.io/api/competitors/comp_xyz/social-metrics" \
  -b "session cookie"
```

```json theme={null}
{
  "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.

```bash theme={null}
curl "https://app.neariq.io/api/competitors/comp_xyz/platform-ratings" \
  -b "session cookie"
```

```json theme={null}
{
  "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.

```bash theme={null}
curl -X POST "https://app.neariq.io/api/competitors/comp_xyz/check" \
  -b "session cookie"
```

```json theme={null}
{
  "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`.

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

```json theme={null}
{
  "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.

```bash theme={null}
curl "https://app.neariq.io/api/competitors/jobs?competitor_id=comp_xyz" \
  -b "session cookie"
```

```json theme={null}
{
  "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.

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

```json theme={null}
{
  "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                                     |