開發者資源/2026 年 1 月 28 日/15 分鐘閱讀

PokeTrace API 開發者指南

PokeTrace API 提供超過 60,000+ 張 Pokemon 卡牌的即時定價數據。本指南涵蓋將 API 整合到您的應用程式所需的一切：身份驗證、端點、回應格式、錯誤處理和生產最佳實踐。

顯示 PokeTrace API 整合和 JSON 回應數據的程式碼編輯器 — 使用美國和歐洲市場的真實定價數據構建 Pokemon 卡牌應用程式

存取 PSA、BGS 和 CGC 鑑定價格以及來自 TCGPlayer、eBay 和 CardMarket 的原始卡價值。

快速入門

三步驟開始運行：（1）在 poketrace.com/dashboard 創建帳戶，（2）生成 API 金鑰，（3）在您的請求中添加 X-API-Key 標頭。就這樣——您已準備好查詢卡牌數據。

所有 API 請求的基本 URL 是 https://api.poketrace.com/v1。所有端點都需要通過 X-API-Key 標頭進行身份驗證。API 返回所有端點結構一致的 JSON 回應。

在 status.poketrace.com 查看 API 狀態。對於 WebSocket 即時更新（僅限 Scale 方案），使用您的 API 金鑰連接到 wss://api.poketrace.com/ws。

身份驗證

所有 API 請求都需要在 X-API-Key 標頭中傳遞 API 金鑰。金鑰可免費創建，速率限制按帳戶而非按金鑰執行——為不同項目創建多個金鑰不會分割您的配額。

Steps

1.在 poketrace.com/dashboard 註冊
2.點擊「創建」生成新的 API 金鑰
3.複製您的金鑰（格式：pc_xxxxxxxx）
4.在請求標頭中包含 X-API-Key: YOUR_KEY

cURL

curl -H "X-API-Key: pc_your_key" https://api.poketrace.com/v1/cards

JavaScript

fetch('https://api.poketrace.com/v1/cards', {
  headers: { 'X-API-Key': 'pc_your_key' }
})

Python

永遠不要將 API 金鑰提交到公開儲存庫。使用環境變數：Node.js 中的 process.env.POKETRACE_API_KEY 或 Python 中的 os.environ['POKETRACE_API_KEY']。

API 端點

API 提供四個核心端點。卡牌按市場分開——美國卡牌有 TCGPlayer 和 eBay 數據，歐洲卡牌有 CardMarket 數據。

GET /v1/cards

列出帶有分頁和篩選的卡牌。返回基本卡牌資訊，不包含完整定價。

Params: limit（最大 100）、cursor、set、search、card_number、variant、market（US/EU）、has_graded

GET /v1/cards?market=US&set=base-set&limit=20

Response:

{
  "data": [{
    "id": "019bff77-befa-771d-bab0-f5909f0a78c9",
    "name": "Charizard",
    "cardNumber": "4/102",
    "set": { "slug": "base-set", "name": "Base Set" },
    "variant": "Holofoil",
    "rarity": "Rare Holo",
    "market": "US",
    "currency": "USD"
  }],
  "pagination": { "hasMore": true, "nextCursor": "YnNfNQ==", "count": 1 }
}

GET /v1/cards/:id

獲取完整卡牌詳情，包含按來源和層級的定價。美國卡牌包含 ebay（所有層級）+ tcgplayer（僅原始）。歐洲卡牌包含 cardmarket（價格趨勢與歷史平均）+ cardmarket_unsold（活躍上架，按層級/國家細分）。

GET /v1/cards/019bff77-befa-771d-bab0-f5909f0a78c9

Response:

// 美國卡牌
{
  "data": {
    "id": "019bff77-befa-771d-bab0-f5909f0a78c9",
    "name": "Charizard",
    "market": "US",
    "currency": "USD",
    "prices": {
      "ebay": {
        "PSA_10": { "avg": 5200, "low": 4800, "high": 5600, "saleCount": 47 },
        "NEAR_MINT": { "avg": 890, "low": 750, "high": 1050, "saleCount": 156 }
      },
      "tcgplayer": {
        "NEAR_MINT": { "avg": 420, "low": 380, "high": 480, "saleCount": 89 }
      }
    }
  }
}

// 歐洲卡牌
{
  "data": {
    "id": "eu_273550",
    "name": "Charizard",
    "market": "EU",
    "currency": "EUR",
    "prices": {
      "cardmarket": { "avg": 385, "avg1d": 380, "avg7d": 375, "avg30d": 370 },
      "cardmarket_unsold": {
        "NEAR_MINT": { "avg": 420, "low": 350, "high": 890, "saleCount": 125, "country": { "DE": { "avg": 410 }, "FR": { "avg": 450 } } }
      }
    }
  }
}

GET /v1/sets

列出所有帶有元數據的卡牌系列。使用系列 slug 來篩選卡牌。

Params: search、game（pokemon、pokemon-japanese）、limit、cursor

GET /v1/sets?search=base&limit=5

Response:

{
  "data": [
    { "slug": "base-set", "name": "Base Set", "releaseDate": "1999-01-09", "cardCount": 102 },
    { "slug": "base-set-2", "name": "Base Set 2", "releaseDate": "2000-02-24", "cardCount": 130 }
  ],
  "pagination": { "hasMore": true, "nextCursor": "YmFzZS1zZXQtMg==", "count": 2 }
}

GET /v1/auth/info

獲取您的 API 金鑰資訊和使用統計。查看剩餘請求數、重置時間和方案詳情。

GET /v1/auth/info

Response:

{
  "data": {
    "key": "pc_a1b2c3d4...",
    "name": "Production",
    "active": true,
    "createdAt": "2026-01-17T10:00:00Z",
    "lastUsedAt": "2026-01-17T12:30:00Z",
    "user": {
      "plan": "Free",
      "remaining": 208,
      "limit": 250,
      "resetsAt": "2026-01-18T00:00:00Z"
    }
  }
}

GET /v1/cards/:id/prices/:tier/history

獲取特定層級的歷史價格數據。適用於圖表和趨勢分析。

Params: period（7d、30d、90d、1y、all）、limit、cursor

GET /v1/cards/019bff77.../prices/PSA_10/history?period=30d

Response:

{
  "data": [
    { "date": "2026-01-27", "source": "ebay", "avg": 5200, "low": 4800, "high": 5600, "saleCount": 3 },
    { "date": "2026-01-26", "source": "ebay", "avg": 5150, "low": 4750, "high": 5500, "saleCount": 5 }
  ],
  "pagination": { "hasMore": true, "nextCursor": "MjAyNi0wMS0yNQ==", "count": 2 }
}

速率限制

速率限制按帳戶而非按金鑰執行。每個回應都包含顯示當前使用量的標頭。

Free

250 / day

僅限美國

僅限原始狀況

Pro

10,000 / day

美國 + 歐洲

原始 + 鑑定（PSA、BGS、CGC）

Scale

100,000 / day

美國 + 歐洲

原始 + 鑑定 + WebSocket

Response Headers

X-RateLimit-Limit — 您方案的每日請求限制
X-RateLimit-Remaining — 今日剩餘請求數
X-RateLimit-Reset — 限制重置的 ISO8601 時間戳
X-Plan — 您當前的方案（Free、Pro、Scale）

積極快取回應。價格每隔幾小時更新一次——快取 15-60 分鐘可顯著減少 API 呼叫。

完整程式碼範例

複製貼上這些範例以開始使用。將 YOUR_KEY 替換為您實際的 API 金鑰。

JavaScript / Node.js

const API_KEY = process.env.POKETRACE_API_KEY;
const BASE_URL = 'https://api.poketrace.com/v1';

async function getCard(cardId) {
  const response = await fetch(`${BASE_URL}/cards/${cardId}`, {
    headers: { 'X-API-Key': API_KEY }
  });
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }
  
  return response.json();
}

async function searchCards(query, market = 'US') {
  const params = new URLSearchParams({ search: query, market, limit: '20' });
  const response = await fetch(`${BASE_URL}/cards?${params}`, {
    headers: { 'X-API-Key': API_KEY }
  });
  return response.json();
}

// 使用方式
const card = await getCard('019bff77-befa-771d-bab0-f5909f0a78c9');
console.log(`${card.data.name}: $${card.data.prices.ebay.PSA_10.avg} (PSA 10)`);

Python

cURL

# 獲取單張卡牌
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.poketrace.com/v1/cards/019bff77-befa-771d-bab0-f5909f0a78c9"

# 搜尋卡牌
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.poketrace.com/v1/cards?search=charizard&market=US&limit=10"

# 列出所有系列
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.poketrace.com/v1/sets?limit=50"

# 查看您的使用量
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.poketrace.com/v1/auth/info"

# 獲取價格歷史
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.poketrace.com/v1/cards/019bff77.../prices/PSA_10/history?period=30d"

錯誤處理

API 使用標準 HTTP 狀態碼。所有錯誤回應都包含 error 和 message 欄位。

400

Bad Request

無效參數

{ "error": "Invalid limit parameter", "message": "Limit must be between 1 and 100" }

401

Unauthorized

缺少或無效的 API 金鑰

{ "error": "API key required", "message": "Include your API key in the X-API-Key header" }

403

Forbidden

需要升級方案

{ "error": "Pro plan required", "message": "Graded card prices require a Pro plan.", "code": "UPGRADE_REQUIRED" }

404

Not Found

資源不存在

{ "error": "Card not found", "message": "No card exists with this ID" }

429

Rate Limited

請求過多

{ "error": "Rate limit exceeded", "message": "Daily limit reached. Resets at 2026-01-18T00:00:00Z", "retryAfter": 3600 }

對於 429 錯誤，使用 retryAfter 欄位（秒）或 X-RateLimit-Reset 標頭。實施指數退避：等待 1 秒，然後 2 秒，然後 4 秒之間重試。

常見問題

美國和歐洲卡牌有什麼區別？

卡牌是特定市場的。美國卡牌有 TCGPlayer 和 eBay 定價，以美元計。歐洲卡牌有 CardMarket 定價，以歐元計，並按國家細分（DE、FR、IT 等）。每張卡只屬於一個市場。

支援哪些鑑定公司？

我們支援 15 家鑑定公司，包括 PSA、BGS、CGC、ACE、TAG 等。鑑定價格在 Pro 和 Scale 方案中可用。每張卡的 gradedOptions 欄位顯示可用的等級。

如何獲取即時價格更新？

WebSocket 連接在 Scale 方案中可用。使用您的 API 金鑰連接到 wss://api.poketrace.com/ws。訂閱特定卡牌以在新銷售發生時接收即時價格更新。

我可以將 API 用於商業項目嗎？

可以。免費方案允許非商業使用。Pro 和 Scale 方案包含商業許可。查看我們的服務條款了解完整詳情。

定價數據有多準確？

價格基於來自 TCGPlayer、eBay 和 CardMarket 的已驗證完成銷售。我們每隔幾小時更新一次。每個價格層級包含信心分數（高、中、低）和 saleCount，以便您評估可靠性。

今天開始構建

獲取您的免費 API 金鑰，開始構建 Pokemon 卡牌應用程式。每天 250 次請求，無需信用卡。

獲取免費 API 金鑰→