レスポンス形式

TCG Price Lookup APIのJSONレスポンス構造、ページネーション、データ型の完全リファレンス。

エンベロープ

すべてのAPIレスポンスは標準的なエンベロープでラップされています。リストエンドポイントの場合：

{
  "data": [...],
  "total": 47,
  "limit": 20,
  "offset": 0
}

単一リソースエンドポイント（カード詳細、一括検索）の場合：

{
  "data": { ... }
}

エンベロープには success、meta、status フィールドはありません。2xx のHTTPステータスコードはリクエストが成功したことを意味します。それ以外の場合はエラーを意味します — エラーハンドリングをご覧ください。

エンベロープフィールド

カードオブジェクト

カードオブジェクトは、検索、カード詳細、一括エンドポイントが返すコアデータ構造です。

完全なカードオブジェクト（/v1/cards/{id} から）

{
  "id": "pokemon-sv4-charizard-ex-006",
  "name": "Charizard ex",
  "game": "pokemon",
  "set": "Paradox Rift",
  "setCode": "sv4",
  "number": "006",
  "rarity": "Double Rare",
  "image": "https://images.tcgpricelookup.com/pokemon/sv4/006.jpg",
  "prices": {
    "market": 42.50,
    "low": 35.00,
    "mid": 41.00,
    "high": 55.00,
    "conditions": {
      "near_mint": 42.50,
      "lightly_played": 38.25,
      "moderately_played": 34.00,
      "heavily_played": 29.75,
      "damaged": 21.25
    },
    "graded": {
      "psa_10": 125.00,
      "psa_9": 75.00,
      "bgs_9_5": 110.00,
      "cgc_9_5": 95.00
    }
  },
  "sources": ["tcgplayer", "ebay"],
  "updatedAt": "2026-04-10T12:00:00Z"
}

カードフィールド

pricesオブジェクト

conditionsオブジェクト

gradedオブジェクト

すべてのグレードがすべてのカードで利用可能なわけではありません。データのないフィールドは null として返されるのではなく、レスポンスから除外されます。

検索結果のカードオブジェクト

/v1/search が返すカードは、完全なカード詳細オブジェクトよりも少ないフィールドを持つ場合があります。価格コンディションとグレーデッドデータは market 価格のみに圧縮される場合があります：

{
  "id": "pokemon-sv4-charizard-ex-006",
  "name": "Charizard ex",
  "game": "pokemon",
  "set": "Paradox Rift",
  "rarity": "Double Rare",
  "prices": {
    "market": 42.50,
    "conditions": {
      "near_mint": 42.50,
      "lightly_played": 38.25
    }
  }
}

すべてのコンディション、グレーデッド価格、ソースメタデータを含む完全なカードオブジェクトを取得するには、/v1/cards/{id} エンドポイントを使用してください。

価格履歴オブジェクト

価格履歴エンドポイント（Traderプラン以上）は異なる構造を返します：

{
  "data": {
    "cardId": "pokemon-sv4-charizard-ex-006",
    "period": "30d",
    "history": [
      { "date": "2026-03-11", "market": 38.00, "low": 32.00, "high": 48.00 },
      { "date": "2026-03-18", "market": 39.50, "low": 33.00, "high": 49.00 },
      { "date": "2026-04-10", "market": 42.50, "low": 35.00, "high": 55.00 }
    ]
  }
}

履歴エントリは古い順に並べられています。date フィールドはISO 8601の日付文字列（YYYY-MM-DD）です。7d と 30d 期間では日次の粒度、90d と 1y では週次の粒度、all では月次の粒度が返されます。

nullとフィールドの欠落の処理

データのないフィールドはレスポンスから除外されます — null 値として存在することはありません。ネストされたフィールドにアクセスする際は、常にオプショナルチェーニングを使用してください：

// 安全 — gradedデータが存在しなくてもエラーにならない
const psa10 = card.prices?.graded?.psa_10 ?? null;

// 安全でない — gradedが欠落している場合にTypeErrorが発生する
const psa10 = card.prices.graded.psa_10;

# 安全 — 辞書アクセスに .get() を使用
psa10 = card.get("prices", {}).get("graded", {}).get("psa_10")

ページネーション

すべてのリストエンドポイント（/v1/search、/v1/sets、/v1/games）は limit と offset パラメータをサポートしています：

GET /v1/search?q=charizard&limit=20&offset=40

すべての結果を反復処理する方法：

async function* fetchAll(query) {
  let offset = 0;
  const limit = 100;
  while (true) {
    const res = await tcg.search(query, { limit, offset });
    yield* res.data;
    offset += limit;
    if (offset >= res.total) break;
  }
}

データ型

• 価格 — USD単位の浮動小数点数。文字列ではありません。
• 日付 — ISO 8601文字列。タイムスタンプにはタイムゾーンが含まれます: "2026-04-10T12:00:00Z"。日付のみのフィールド: "2026-04-10"。
• ID — URLセーフな文字列。エンドポイントパスとクエリパラメータで直接使用できます。
• カウント — 整数。浮動小数点数ではありません。