RoomScope

最後更新

快速開始

只要三步：建立金鑰、呼叫端點、讀取資料來源。每個請求都從工作區的點數錢包計費，也就是主控台使用的同一個錢包。

事前準備

  • 一個 RoomScope 工作區。若還沒有，請先免費開始；Free 方案即可透過 API 讀取快取的榜單。
  • 具備管理金鑰權限（keys:manage）的角色。工作區擁有者預設即具備此權限。

1. 建立 API 金鑰

在主控台開啟 設定 → API 金鑰 → 建立金鑰，為金鑰命名並選擇所需的權限範圍。密鑰只會顯示一次，請存放在你的密鑰管理工具中。之後只能看到金鑰前綴。

2. 送出第一個請求

取得越南今天的官方日榜。請先在環境變數中設定 ROOMSCOPE_API_KEY。

curl "https://api.toktokdata.live/v1/rankings/official?board=daily&region=VN&period=current&limit=10" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY" \  -H "Accept: application/json"

3. 讀取回應

每個成功的回應都包含一個 data 物件與一個 provenance 物件。資料來源會告訴你訊號的觀測時間以及覆蓋的完整程度；請把它視為結果的一部分，而不是附帶的中繼資料。

200 OK
{  "data": {    "board": {      "publishable": true,      "periodKey": "2026-11-01",      "resetAt": "2026-11-02T00:00:00Z",      "coverage": { "completeBoards": 24, "expectedBoards": 24 },      "entries": [        {          "rank": 1,          "creatorUid": "7123456789012345678",          "uniqueId": "room.one",          "nickname": "Room One",          "score": 2410000,          "isLive": true,          "leagueClass": null,          "movement": "same",          "masked": false,          "unmaskTier": null        }      ]    }  },  "provenance": { "coverageStatus": "observed", "observedAt": "2026-11-01T09:58:12Z" }}

若榜單尚未可發布（publishable: false），entries 清單會是空的，並由 provenance.coverageStatus 說明原因。隱藏名稱的項目（masked: true）會在 unmaskTier 中標示可顯示其名稱的方案等級。

下一步

  • 身分驗證：權限範圍、金鑰輪替，以及 401 或 403 代表的意義。
  • 錯誤：錯誤回應格式，以及何時應該重試。
  • 排行榜 API 參考：GET /v1/rankings/official 的所有參數。
這個頁面對你有幫助嗎？