資料分析 API

資料分析 API 可讓您以程式化方式存取已連線 SNS 帳號的多頻道成效資料、粉絲人數記錄與貼文互動指標。

📌 端點

方法	路徑	說明	必要權限範圍
`GET`	`/v1/brand/analytics`	按時間範圍、平台或連線查詢詳細指標	`analytics:read` 或 `*`
`GET`	`/v1/brand/analytics/overview`	所有品牌通路的 30 天快速摘要	`analytics:read` 或 `*`

📊 詳細分析 (`GET /v1/brand/analytics`)

根據篩選條件查詢彙總和各通路的指標。

查詢參數

參數	類型	必要性	預設值	說明
`range`	`string`	選填	`30d`	時間範圍（`7d`、`14d`、`30d`、`90d` 或自定義 `YYYY-MM-DD..YYYY-MM-DD`）
`sns_type`	`string`	選填	-	按平台篩選（`instagram`、`threads`、`bluesky` 等）
`connection_id`	`string`	選填	-	按特定連線 ID 篩選

請求範例

curl -X GET "https://api.ankk.app/v1/brand/analytics?range=30d&sns_type=instagram" \
  -H "Authorization: Bearer spk_live_xxxxxxxx"

回應範例 (`200 OK`)

{
  "range": {
    "start": "2026-07-17T00:00:00Z",
    "end": "2026-08-16T00:00:00Z",
    "preset": "30d"
  },
  "totals": {
    "followers": 12500,
    "followers_change": 340,
    "published_posts": 28,
    "impressions": 84200,
    "reach": 61500,
    "engagement_rate": 4.8,
    "likes": 3210,
    "comments": 412,
    "shares": 180,
    "saves": 250
  },
  "by_channel": [
    {
      "connection_id": "conn_01jm8x9k2example",
      "sns_type": "instagram",
      "username": "acme_official",
      "followers": 12500,
      "posts_count": 28,
      "metrics_status": "synced"
    }
  ]
}

📈 品牌概覽 (`GET /v1/brand/analytics/overview`)

快速取得適合儀表板小工具與每日摘要使用的 30 天高階彙總資料。

請求範例

curl -X GET "https://api.ankk.app/v1/brand/analytics/overview" \
  -H "Authorization: Bearer spk_live_xxxxxxxx"

回應範例 (`200 OK`)

{
  "brand_ref": "brand_01jm8v4k9example",
  "active_connections": 4,
  "summary_30d": {
    "total_published": 54,
    "total_failed": 1,
    "total_followers": 28400,
    "total_impressions": 195000
  },
  "synced_at": "2026-08-16T03:00:00Z"
}

⚠️ 指標與限制說明

方案限制：免費方案支援最近 30 天的指標。增長方案（Growth）及以上方案可提供更長的保留期限（90 天以上）。
解讀 0 與 null：
- 0：測量的指標值確實為零。
- null / unsupported：平台 API 不支援此指標，或權限未經驗證。

🔗 相關文件