今天很熱
閱讀最新穩定的熱門影片快照。
GET
https://api.shortsmonkey.com/v1/rankings/hot-today?region=US&tier=all&limit=20每實際 1-20 個項目 1 個學分
今天很熱#
閱讀最新穩定的熱門影片快照。
驗證#
發送 Authorization: Bearer sm_live_...。切勿將完整金鑰放入 URL、cookie、內文、日誌或分析中。
數據新鮮度#
排名讀取工作人員發布的穩定快照。公共讀取永遠不會觸發 YouTube 刷新。
要求#
| 物品 | 價值 | 描述 |
|---|---|---|
| 方法 | GET | HTTP 請求方法 |
| 完整 URL | https://api.shortsmonkey.com/v1/rankings/hot-today?region=US&tier=all&limit=20 | 生產 API URL |
| 驗證 | Authorization: Bearer sm_live_... | 僅在標頭中發送完整密鑰 |
| 內容類型 | 無請求內文 | GET 請求沒有請求正文 |
| 製作人員 | 每實際 1-20 個項目 1 個學分 | 錯誤響應花費 0 點 |
請求參數#
| 姓名 | 地點 | 類型 | 必需的 | 預設 | 值或限制 | 描述 |
|---|---|---|---|---|---|---|
region | 詢問 | string | 不 | 所有地區 | 2–16 個字符 | 區域代碼，例如 US 或 JP |
tier | 詢問 | string | 不 | all | S / A / B / C / all | 熱層過濾器 |
limit | 詢問 | integer | 不 | 20 | 1–50 | 此頁面上的最大項目數 |
all_cursor | 詢問 | string | 不 | — | data.all_data.next_cursor | 取得下一個未過濾的頁面 |
filter_cursor | 詢問 | string | 不 | — | data.filter_data.next_cursor | 取得下一個過濾頁面而不更改過濾器 |
cursor | 詢問 | string | 不 | — | 已棄用的兼容性參數 | filter_cursor 的別名；請勿同時傳送 |
成功響應字段#
all_data 是穩定快照中未經過濾的頁面； filter_data 是來自端點預設值和請求過濾器之後的相同快照的頁面。每個結果獨立分頁。
點表示法表示嵌套對象，[] 表示陣列項目。未知訂閱者計數為 null 和 subscriber_count_hidden: true。一個請求按回傳的較大項目數計費一次，而不是兩組的總和。
| 田野路徑 | 類型 | 可空 | 描述 |
|---|---|---|---|
data.all_data.items | array<object> | 不 | 目前頁面上未過濾的影片項 |
data.all_data.items[].video_id | string | 不 | YouTube 視訊 ID |
data.all_data.items[].title | string | 不 | 影片標題 |
data.all_data.items[].video_url | string | 不 | YouTube 視訊 URL |
data.all_data.items[].channel.id | string | 是的 | 頻道號碼 |
data.all_data.items[].channel.title | string | 不 | 頻道標題 |
data.all_data.items[].channel.subscribers | integer | 是的 | 訂戶數量； null 隱藏時 |
data.all_data.items[].channel.subscriber_count_hidden | boolean | 不 | 是否隱藏訂閱人數 |
data.all_data.items[].views | integer | 不 | 觀看次數快照 |
data.all_data.items[].views_to_subscribers_ratio | number | 是的 | 觀看次數與訂閱者比 |
data.all_data.items[].opportunity_score | number | 是的 | 機會分數 |
data.all_data.items[].duration_seconds | integer | 不 | 影片時長（以秒為單位） |
data.all_data.items[].published_at | string(date-time) | 是的 | 影片發佈時間（UTC ISO 8601） |
data.all_data.items[].snapshot_at | string(date-time) | 是的 | 數據採集時間 |
data.all_data.items[].niche | string | 是的 | 利基或類別 |
data.all_data.items[].track | string | 是的 | 資料集軌道標識符 |
data.all_data.items[].region | string | 是的 | 地區代碼 |
data.all_data.items[].reasons | array<string> | 不 | 排名原因 |
data.all_data.items[].video_type | string | 不 | shorts 或 long |
data.all_data.next_cursor | string | 是的 | 此結果集的下一頁 cursor；null 完成後 |
data.filter_data.items | array<object> | 不 | 預設和請求過濾器後的視訊項目 |
data.filter_data.items[].video_id | string | 不 | YouTube 視訊 ID |
data.filter_data.items[].title | string | 不 | 影片標題 |
data.filter_data.items[].video_url | string | 不 | YouTube 視訊 URL |
data.filter_data.items[].channel.id | string | 是的 | 頻道號碼 |
data.filter_data.items[].channel.title | string | 不 | 頻道標題 |
data.filter_data.items[].channel.subscribers | integer | 是的 | 訂戶數量； null 隱藏時 |
data.filter_data.items[].channel.subscriber_count_hidden | boolean | 不 | 是否隱藏訂閱人數 |
data.filter_data.items[].views | integer | 不 | 觀看次數快照 |
data.filter_data.items[].views_to_subscribers_ratio | number | 是的 | 觀看次數與訂閱者比 |
data.filter_data.items[].opportunity_score | number | 是的 | 機會分數 |
data.filter_data.items[].duration_seconds | integer | 不 | 影片時長（以秒為單位） |
data.filter_data.items[].published_at | string(date-time) | 是的 | 影片發佈時間（UTC ISO 8601） |
data.filter_data.items[].snapshot_at | string(date-time) | 是的 | 數據採集時間 |
data.filter_data.items[].niche | string | 是的 | 利基或類別 |
data.filter_data.items[].track | string | 是的 | 資料集軌道標識符 |
data.filter_data.items[].region | string | 是的 | 地區代碼 |
data.filter_data.items[].reasons | array<string> | 不 | 排名原因 |
data.filter_data.items[].video_type | string | 不 | shorts 或 long |
data.filter_data.next_cursor | string | 是的 | 此結果集的下一頁 cursor；null 完成後 |
data.all_data.items[].tier | string | 不 | 熱門層 S / A / B / C |
data.filter_data.items[].tier | string | 不 | 熱門層 S / A / B / C |
meta.request_id | string | 不 | 請求追蹤 ID |
meta.snapshot_id | string | 不 | 穩定的快照ID |
meta.snapshot_at | string(date-time) | 不 | 快照時間戳 |
meta.data_status | string | 不 | 資料集狀態 |
credits.cost | integer | 不 | 實際收取的積分 |
credits.remaining | integer | 不 | 剩餘帳戶積分 |
credits.period_ends_at | string(date-time) | 不 | 當前信用期結束 |
分頁和 cursor#
將 all_data.next_cursor 傳送為 all_cursor，將 filter_data.next_cursor 傳送為 filter_cursor。 cursor是獨立的、不透明的、經過簽名的、24小時內有效；舊版 cursor 只是 filter_cursor 的別名。
電子標籤#
排名支援If-None-Match。命中返回 HTTP 304 和 X-Credits-Cost: 0。
錯誤和速率限制#
每個錯誤都包含 code、穩定英文 message、request_id 和 details。所有 4xx/5xx 回應的成本為零。
| HTTP 狀態 | 程式碼 | 原因 | 建議採取的行動 |
|---|---|---|---|
| 400 | INVALID_REQUEST | 參數格式、組合或範圍無效 | 使用 details.issues 修正參數 |
| 401 | INVALID_API_KEY | 密鑰無效或無效 | 檢查承載頭和金鑰狀態 |
| 402 | SUBSCRIPTION_REQUIRED / CREDITS_EXHAUSTED | 訂閱或積分不可用 | 檢查計劃、平衡和關鍵安全預算 |
| 429 | RATE_LIMITED | 超出速率或併發限制 | Retry-After 間隔後重試 |
| 503 | DATA_STALE / SERVICE_UNAVAILABLE | 數據或服務暫時無法使用 | 稍後重試並保留 request_id |
curl -X GET "https://api.shortsmonkey.com/v1/rankings/hot-today?region=US&tier=all&limit=20" \
-H "Authorization: Bearer $SHORTSMONKEY_API_KEY"