端點
所有端點皆為 GET、回傳 JSON，且無需金鑰。
| 端點 | 回傳內容 |
|---|---|
| /api/v1/market | 指定範圍的一頁排名，附快照中繼資料 |
| /api/v1/cards/<id> | 以 id 取單張卡；未入榜則回 404 及錯誤內容 |
查詢參數
無效值一律回 HTTP 400，不會靜靜退回預設值。
| 參數 | 可接受值 | 備註 |
|---|---|---|
| scope | all、pokemon、one-piece、watchlist | 其他值回 400 |
| page | 正整數 | 非數字或 0 回 400 |
| pageSize | 正整數 | 會被限制在伺服器上限內 |
回應欄位
市場回應會把卡片清單連同快照身分一併包起，讓已儲存的回應永遠追溯得回產生它的那次建置。
| 欄位 | 意義 |
|---|---|
| generation | 回應所屬快照建置的識別碼 |
| generatedAt | 快照建置的時間 |
| effectiveAt | 數字所代表的日期 |
| coverage | 快照相對其聲稱範圍的完整程度 |
| count | 本回應中的卡片數量 |
| cards | 已排名卡片，各自帶有價格、鑑定數量與市值 |
請求範例
取得寶可夢範圍的第一頁：
curl -s "https://cardzmarketcap.com/api/v1/market?scope=pokemon&page=1"回應會在邊緣短暫快取。請以 effectiveAt 欄位判斷數字屬於哪一天，而不是看回應時間。
更新頻率
每日發佈新快照，API 提供當前那一份。舊的 generation 不會由這些端點提供。
若你要儲存回應，請連同 generation 與 effectiveAt 一起存。不同 generation 的兩個數字，沒有日期就不可比較。
合理使用
API 公開且免驗證，所以請維持合理的請求頻率：讀一頁、快取起來，不要用快過資料變動的速度輪詢。快照一日才動一次。
過量自動化流量可能被限速。若你需要整批存取，請先聯絡我們，不要用爬的。
出處標示與授權
數字可依 CC BY 4.0（https://creativecommons.org/licenses/by/4.0/）引用及轉載，惟須註明出處為 CardZ Marketcap，並連回所引用的頁面或端點。
標示時必須附上該數字的生效日期，因為市值每日重新計算。
標示格式
CardZ Marketcap，https://cardzmarketcap.com，數據截至 2026-08-28
可機讀檔案
供爬蟲、代理程式與語言模型使用：
- /llms.txt — 本站與主要頁面的簡短說明
- /llms-full.txt — 加長版本，附計算方法摘要
- /sitemap.xml — 所有可索引頁面
CardZ Marketcap 是集換式卡牌的價格指數，不是加密貨幣、不是代幣，也不是上市公司。本站沒有任何代幣代號，與名為 CARDS 的加密資產無關。
