Visibility & Analytics API

Portal routes for visibility scoring, peer benchmarking, listing verification, AEO visibility, and related analytics.

Freshness Policy

Score-critical visibility routes return Cache-Control: private, no-store:

• GET /api/visibility/scores
• GET /api/visibility/score-history
• GET /api/visibility/competitors
• GET /api/visibility/competitor-suggestions
• GET /api/visibility/aeo
• GET /api/visibility/listing-health
• GET /api/exports/report

GET /api/visibility/scores

Returns the latest visibility score payload sourced from the latest completed scored run.

Auth: Required (portal session)

Response:

{
  "ok": true,
  "data": {
    "runId": "run_abc123",
    "asOf": "2026-02-24T14:00:00Z",
    "overall": {
      "rawScore": 39.9,
      "dynamicScore": 45.0,
      "confidence": 76.0,
      "calculatedAt": "2026-02-24T14:00:00Z"
    },
    "tiers": [],
    "components": [],
    "lastScanDate": "2026-02-24T14:00:00Z"
  }
}

GET /api/visibility/score-history

Returns historical run-scoped score points.

Auth: Required

GET /api/visibility/competitors

Returns competitor benchmark comparison with policy-filtered peers.

Auth: Required

Response (shape):

{
  "ok": true,
  "data": {
    "client": {
      "client_id": "client_corevision",
      "raw_score": 39.9,
      "dynamic_score": 45.0,
      "overall_score": 45.0,
      "run_id": "run_abc123",
      "asOf": "2026-02-24T14:00:00Z",
      "tiers": {},
      "components": {}
    },
    "competitors": [],
    "comparison": {
      "metric": "dynamic_score",
      "dataAsOf": "2026-02-24T14:00:00Z",
      "isStale": false,
      "competitor_avg": 23.0,
      "client_vs_avg": 22.0,
      "rank": 1,
      "total_in_market": 4,
      "component_comparison": []
    }
  }
}

GET /api/visibility/competitor-suggestions

Returns peer-selection transparency metadata.

Auth: Required

Response (shape):

{
  "ok": true,
  "data": {
    "clientId": "client_corevision",
    "clientName": "CoreVision",
    "currentCompetitors": ["example.com"],
    "suggestions": [
      {
        "name": "Example Advisory Group",
        "domain": "exampleadvisory.com",
        "source": "industry_directory",
        "relevanceScore": 82,
        "specialtyOverlap": 0.88,
        "selectionReason": "Source: industry directory | fit score 82/100 | specialty overlap 88%",
        "excludedReason": null,
        "isCurrentCompetitor": false
      }
    ]
  }
}

GET /api/visibility/aeo

Returns AI search visibility metrics.

Auth: Required

Response fields include:

• queryMode: local_discovery | industry_b2b | online_first
• generated_queries: string[]
• coverage: standard | limited
• aeo_confidence: scanner-native confidence object (score, band, summary, detail, factors)
• scoring fields (aeo_visibility_score, visibility_score, position_score, sentiment_score, accuracy_score)

GET /api/visibility/listing-health

Returns directory listing verification details.

Auth: Required

Response fields include:

• directory_results[].verificationStatus: verified | candidate | not_found
• directory_results[].listedName
• directory_results[].listedAddress
• directory_results[].listedPhone
• directory_results[].listedDomain
• directory_results[].nameMatch, addressMatch, phoneMatch, napConsistent

GET /api/visibility/overview

Returns top-level visibility dashboard overview data.

Auth: Required

GET /api/visibility/website-analytics

Returns website analytics (Vercel + connected sources).

Auth: Required

GET /api/visibility/social-metrics

Returns social profile metrics.

Auth: Required

GET /api/visibility/action-plan

Returns phased visibility action checklist data.

Auth: Required

GET /api/visibility/recommendations

Returns recommendation cards with impact/effort/category metadata.

Auth: Required

GET /api/visibility/content-impact

Returns content impact metrics for visibility.

Auth: Required

GET /api/visibility/report

Returns report availability metadata for the current client.

Auth: Required

Response (shape):

{
  "ok": true,
  "data": {
    "hasReport": true,
    "clientName": "CoreVision",
    "overallScore": 45,
    "lastScanDate": "2026-02-24T14:00:00Z"
  }
}

GET /api/exports/report

Generates the latest Visibility PDF report and returns a download URL.

Auth: Required

Temporary dependency failure (503):

{
  "ok": false,
  "error": "PDF export is temporarily unavailable. Please try again shortly."
}

Response (shape):

{
  "ok": true,
  "url": "https://blob.vercel-storage.com/reports/visibility/corevision-visibility-report-2026-02-24.pdf",
  "filename": "corevision-visibility-report-2026-02-24.pdf",
  "size": 184234
}

Analytics Endpoints

GET /api/analytics/heatmap

Auth: Required

GET /api/analytics/reviews

Auth: Required

GET /api/analytics/sources

Auth: Required