TRENDS MONITOR / API V1

把趨勢接入你的工具。

公開、唯讀、免 API key。JSON 回應支援跨網站呼叫（CORS）。API 使用本次部署的資料快照，每次請求不會重新抓取來源。

兩個端點

GET 端點	資料與更新排程（香港時間）
`/api/v1/products`	PRODUCT RADAR，每日 09:30、21:30 採集，成功部署後更新。
`/api/v1/github-trending`	GitHub 所有語言每日榜，每日 09:00 採集，成功部署後更新。

搜尋、篩選與分頁

參數	用途
`q`	兩個端點皆可用。搜尋名稱及描述，不分大小寫。
`limit / offset`	兩個端點皆可用。預設 50 / 0；limit 為 1–200，offset 為 0–1,000,000。以回傳的 next_offset 讀取下一頁，null 表示結束。
`signal`	產品訊號：hot（熱門）、rising（快速上升）、steady（持續升溫）、watch（值得留意）。
`source`	產品來源家族：appstore、googleplay、producthunt、hn、itch。
`market`	產品市場，如 HK、US、TW、GLOBAL。與 source 同用時，必須符合同一筆來源證據。
`category / type`	產品用途／形式，對應 extra.category（如「生產力」）及 extra.np_type（如 app、web、web_game）。完全匹配，不分大小寫。
`language`	GitHub 程式語言，如 Python、TypeScript、Go。不分大小寫。只篩選已採集的全球榜，並非另抓 GitHub 的語言專屬榜。

參數可組合，每個參數只能提供一次。字串長度 1–200 字元。空值、未知參數、錯誤分頁或無效 signal 回傳 400。查無結果回傳 200 及空 items。

產品 signal 是整個產品的綜合訊號；source / market 篩選來源證據，不表示該訊號一定來自所選市場。結果維持網站原排序，篩選後不重編 rank。

直接呼叫

curl 'https://trends-monitor.pages.dev/api/v1/products?signal=rising&market=HK&limit=20'

curl 'https://trends-monitor.pages.dev/api/v1/github-trending?language=Python'

const response = await fetch(
  'https://trends-monitor.pages.dev/api/v1/products?limit=20'
);
if (!response.ok) throw new Error(`API error: ${response.status}`);
const { items, snapshot_at, next_offset } = await response.json();

回應格式

api_version、dataset、snapshot_at、previous_snapshot_at、timezone、total（篩選後總數）、count（本頁數量）、limit、offset、next_offset、filters、sources、methodology、items。

每個 item 包含 item_id, title, url, rank, score, status, rank_delta, extra。PRODUCT RADAR 的 extra 保留用途、訊號、來源證據及歷史；GitHub 的 extra 包含 repository、language、desc、stars、forks、stars_today。來源未提供的選填欄位可能缺省或為 null。

資料時間與含義

snapshot_at 是該榜單採集時間／日期，不是 API 請求時間。請自行檢查是否過期。GitHub 日期以香港時間表示。
PRODUCT RADAR 保留失敗來源的最近成功觀察。檢查 sources[].status / updated_at 及 extra.evidence[].observed_at / fresh；fresh、signals 均是採集時計算，API 不會隨時間重新判定。
GitHub 的 score 是原榜提供的今日新增 Stars；總 Stars 在 extra.stars。GitHub 的 sources 為空陣列：目前沒有獨立的採集錯誤狀態，請檢查 snapshot_at。
排名升跌比較前次成功採集，不保證相隔剛好一天。產品訊號代表榜單與討論熱度，不代表下載量、營收或用戶增長。
分頁期間若部署新快照，結果可能變動；需完整一致資料時，每頁比對 snapshot_at，變更後從 offset=0 重讀。

HTTP 行為

支援 GET、HEAD、OPTIONS。瀏覽器快取 60 秒，共享快取最多 300 秒。錯誤不快取。400：參數錯誤；404：端點不存在；405：不支援寫入；503：已發布資料無法讀取（Retry-After: 300）。

{"api_version":"v1","error":{"code":"invalid_parameter","message":"limit must be an integer from 1 to 200"}}

GitHub 官方 API？

GitHub 提供 repository 搜尋 API，但目前公開文件未提供 Trending 每日榜端點。本站讀取 GitHub Trending 公開頁面並提供自己的資料 API；按總 Stars 排序的搜尋結果不等同每日 Trending 榜。