开发者资源/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": 458,
      "limit": 500,
      "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 金钥→