PokeTrace
←블로그로 돌아가기
개발자 리소스/2026년 1월 28일/15 분 읽기

PokeTrace API 개발자 가이드

PokeTrace API는 60,000개 이상의 포켓몬 카드에 대한 실시간 가격 데이터를 제공합니다. 이 가이드는 API를 애플리케이션에 통합하는 데 필요한 모든 것을 다룹니다: 인증, 엔드포인트, 응답 형식, 오류 처리, 프로덕션 모범 사례.

JSON 응답 데이터가 있는 PokeTrace API 통합을 보여주는 코드 에디터
미국 및 유럽 시장의 실시간 가격 데이터로 포켓몬 카드 애플리케이션 구축

TCGPlayer, eBay, CardMarket의 미등급 카드 가치와 함께 PSA, BGS, CGC 등급 가격에 접근하세요.

01

빠른 시작

세 단계로 시작하세요: (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에 연결하세요.

02

인증

모든 API 요청은 X-API-Key 헤더에 전달되는 API 키가 필요합니다. 키는 무료로 생성할 수 있으며 속도 제한은 키가 아닌 계정별로 적용됩니다—할당량을 나누지 않고 다른 프로젝트에 대해 여러 키를 생성하세요.

Steps

  1. 1.poketrace.com/dashboard에서 가입
  2. 2.'생성'을 클릭하여 새 API 키 생성
  3. 3.키 복사 (형식: pc_xxxxxxxx)
  4. 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'].
03
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 }
      }
    }
  }
}
GET /v1/sets
메타데이터가 포함된 모든 카드 세트 목록. 카드 필터링에 세트 슬러그 사용.
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 }
}
04
속도 제한
속도 제한은 키가 아닌 계정별로 적용됩니다. 모든 응답에는 현재 사용량을 보여주는 헤더가 포함됩니다.
무료
250 / day
미국만
미등급 상태만
프로
10,000 / day
미국 + 유럽
미등급 + 등급 (PSA, BGS, CGC)
스케일
100,000 / day
미국 + 유럽
미등급 + 등급 + WebSocket
Response Headers
  • X-RateLimit-Limit — 플랜의 일일 요청 한도
  • X-RateLimit-Remaining — 오늘 남은 요청
  • X-RateLimit-Reset — 한도 리셋 ISO8601 타임스탬프
  • X-Plan — 현재 플랜 (Free, Pro, Scale)
응답을 적극적으로 캐시하세요. 가격은 몇 시간마다 업데이트됩니다—15-60분 캐싱으로 API 호출이 크게 줄어듭니다.
05
완전한 코드 예제
시작하려면 이 예제를 복사-붙여넣기하세요. 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();
}

// 사용
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/auth/info"
06
오류 처리
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초 대기.
07
자주 묻는 질문
미국 카드와 유럽 카드의 차이점은 무엇인가요?
카드는 시장별로 구분됩니다. 미국 카드는 USD로 TCGPlayer와 eBay 가격을 가집니다. 유럽 카드는 국가별 분류(DE, FR, IT 등)가 있는 EUR로 CardMarket 가격을 가집니다. 각 카드는 하나의 시장에만 속합니다.
어떤 등급 회사를 지원하나요?
PSA, BGS, CGC, SGC, ACE, TAG 등 15개 등급 회사를 지원합니다. 등급 가격은 Pro 및 Scale 플랜에서 이용 가능합니다. 각 카드의 gradedOptions 필드에 이용 가능한 등급이 표시됩니다.
실시간 가격 업데이트를 어떻게 받나요?
WebSocket 연결은 Scale 플랜에서 이용 가능합니다. API 키로 wss://api.poketrace.com/ws에 연결하세요. 특정 카드를 구독하면 새 판매 발생 시 즉시 가격 업데이트를 받습니다.
상업 프로젝트에 API를 사용할 수 있나요?
네. 무료 티어는 비상업적 사용을 허용합니다. Pro 및 Scale 플랜에는 상업 라이선스가 포함됩니다. 전체 세부 사항은 이용약관을 확인하세요.
가격 데이터는 얼마나 정확한가요?
가격은 TCGPlayer, eBay, CardMarket의 검증된 완료 판매 기반입니다. 몇 시간마다 업데이트됩니다. 각 가격 티어에는 신뢰도 점수(high, medium, low)와 saleCount가 포함되어 신뢰성을 평가할 수 있습니다.
오늘 빌드 시작
무료 API 키를 받고 포켓몬 카드 애플리케이션 구축을 시작하세요. 하루 250 요청, 신용카드 불필요.
무료 API 키 받기→