Trading Card Studioby プレミアムヴォールト
ナビゲーションを開く
Trading Card Studio API
認証
ドキュメント

Trading Card Studio APIドキュメント

マルチゲームのカタログの読み方です。GET /health と GET /catalog/games はキー不要です。それ以外のカタログ呼び出しはAPIキーを使います。

サンプルは https://api.tradingcardstudio.com/v1 を呼びます。
公式カタログ
マルチゲームの正規化データ
セットと印刷
リリースグループと言語
開発者向け
キー、ページネーション、クイックスタート
ベースURL:
https://api.tradingcardstudio.com/v1

クイックスタート

本番カタログの読み取りは4ステップです。最初のリクエストにキーは不要です。Hobbyist と Builder では、一部のカードについて価格データを提供します（提供がある場合）。価格データのないカードも多くあります。Freeは同じルートで、価格フィールドが空、prices_included は false です。Hobbyist と Builder でも、価格データのないカードやプリントでは、/prices ルートは 200 と空の data 配列を返します。

1

本番のベースURLを使う

このページのサンプルはすべて本番APIを呼びます。 https://api.tradingcardstudio.com/v1
2

APIキーを取得する

ダッシュボードでキーを発行。キーはサーバー側で保持し、カタログ呼び出しの X-API-Key に入れます。キーなしで使えるのは GET /health と GET /catalog/games だけです。
無料APIキーを発行
3

カタログリクエストを送る

このリクエストは公開です。キー付きのカード検索は同じホストに X-API-Key を付けます。タイトル一覧は 対応タイトル
cURL
curl "https://api.tradingcardstudio.com/v1/catalog/games"
4

ページネーションと上限を確認する

GET /catalog/games はタイトル一覧を1件のオブジェクトで返します。カタログの一覧は limit と offset を受け付けます。limit の既定は 50 で、1から200の値として読まれます。1未満は1、200超は200、数値でない値は50として読まれます。offset の既定は0です。次のページの前に pagination.total を確認します。

認証

キー不要なのは GET /health と GET /catalog/games だけです。ゲーム、セット、カード、印刷など、それ以外のカタログ呼び出しは APIキーを X-API-Key ヘッダーで送ります。

APIキーの形式

  • ->発行キー: tv_live_xxxxxxxxxxxxxxxxxxxxxxxx
セキュリティ
APIキーをクライアントコード、公開リポジトリ、ログ、スクリーンショットに置かないでください。サーバー側の環境変数を使い、漏えいしたらローテーションしてください。

認証方法

X-API-Key ヘッダー
curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/games"

レート制限

各プランのカタログ読み取りは、UTCの暦月ごとの上限です。Freeは500、Hobbyistは10,000、Builderは50,000です。

計上されるGETは /games、/sets、/sets/{setRef}、/cards、/cards/{id}、/cards/{id}/siblings、/cards/{id}/localizations、/cards/{id}/prices、/concepts/{id}、/prints/{id}、/prints/{id}/prices です。これらのルートにはAPIキーを送ります。同じアカウントのサインイン済みセッションからのリクエストも、同じ上限に計上されます。

Hobbyist と Builder では、一部のカードについて価格データを提供します（提供がある場合）。価格データのないカードも多くあります。Freeでは同じ形式で価格フィールドが空になり、prices_included: false が返ります。Freeでも、価格フィールドが空の応答は同じ上限に計上されます。

上限に達すると429が返ります。次のUTC月1日 00:00 まで待つか、Retry-After の秒数だけ待ってから再試行してください。429もリクエストとして計上されるので、待たずに繰り返さないでください。月500の上限では1件目から500件目まで成功し、501件目以降は429です。

プラン月次のカタログ読み取りAPIキー
Free500 / UTC暦月1
Hobbyist10,000 / UTC暦月上限なし
Builder50,000 / UTC暦月上限なし

429レスポンス

HTTP 429 の Retry-After は、次のUTC月1日 00:00 までの秒数です。その秒数だけ待ってから、カタログを再度呼び出します。

レスポンス例

月500枠の件数の例です。error、message、window は実際の文言です。

{
  "error": "rate_limited",
  "message": "This account has used its monthly catalog request allowance.",
  "window": "month",
  "used": { "monthly": 501 },
  "limits": { "monthly": 500 }
}

識別子

APIはカタログIDと、ゲーム固有のセットコードを分けています。

カードID

97997e2be098df0ff51e0e945dda577a

カードIDは32文字の16進です。カードルートは、同じIDをハイフン付きUUIDとしても受け付けます。カードのレスポンスは32文字の16進です。印刷とセットのレスポンスはハイフン付きUUIDです。

セット参照

EX-09

セット詳細はカタログが返すセットコード（例: EX-09）を受け付けます。ゲーム間でコードが衝突する場合は game を付けてください。

レスポンス形状

成功したJSONは data を返します。GET /catalog/games はページネーションなしでタイトル一覧を返します。キー付き一覧は limit、offset、total の pagination を付けます。total_is_estimate が true になるのは、フィルタなし、または game だけの GET /cards だけです。詳細は data 内の単一オブジェクトです。GET /cards/{id}、GET /cards/{id}/prices、GET /prints/{id}、GET /prints/{id}/prices は prices_included と upgrade_hint も返します。エラーは error を返し、キー付きカタログでは message も返します。

ページネーション付きカードレスポンス
{
  "data": [
    {
      "id": "97997e2be098df0ff51e0e945dda577a",
      "name": "Abbadomon",
      "card_number": "EX9-055 R",
      "rarity": "r",
      "language_code": "en",
      "game_slug": "digimon-card-game",
      "set_code": "EX-09",
      "set_name": "EXTRA BOOSTER VERSUS MONSTERS",
      "image_url": "https://images.tradingcardstudio.com/card-images/faa8f84b5d4e091fc3bf2257080f9c1600b9d10e13ab84f59113026a32845cdf.png",
      "attributes": { "cost": "11", "level": "Lv.6", "card_type": "Digimon" },
      "updated_at": "2026-10-12T00:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1,
    "total_is_estimate": false
  }
}
エラーレスポンス
{
  "error": "unauthorized"
}
見つからない
{
  "error": "set_not_found"
}
APIリファレンス

公開エンドポイント

GET/health公開

サービスヘルス

APIが稼働しているかを確認します。APIキーは不要です。

レスポンスのフィールド

フィールド型説明
okbooleanAPIが稼働しているときは true。
databasebooleanカタログデータを読み込めるときは true。
releasestring | null現在のAPIリリース。なければ null。
リクエスト例
curl "https://api.tradingcardstudio.com/v1/health"
レスポンス例
{
  "ok": true,
  "database": true,
  "release": null
}
GET/catalog/games公開

公開カタログタイトル

カタログ内のすべてのゲームを、セット数、印刷数、カード数、封入製品数とあわせて返します。APIキーは不要です。

レスポンスのフィールド

フィールド型説明
data[].slugstringゲームのスラッグ。他のエンドポイントの game パラメータに使えます。
data[].namestringゲーム名。
data[].setsintegerセット数。
data[].printsintegerカードの印刷数。
data[].conceptsintegerカードの種類数。複数のセットや言語で印刷されたカードは1枚として数えます。
data[].sealed_productsintegerブースターやデッキなどの封入製品数。
リクエスト例
curl "https://api.tradingcardstudio.com/v1/catalog/games"
レスポンス例
{
  "data": [
    {
      "slug": "pokemon",
      "name": "Pokemon TCG",
      "sets": 1717,
      "prints": 172457,
      "concepts": 154834,
      "sealed_products": 12534
    },
    {
      "slug": "one-piece-card-game",
      "name": "One Piece Card Game",
      "sets": 429,
      "prints": 28314,
      "concepts": 3039,
      "sealed_products": 668
    }
  ]
}

カタログエンドポイント

GET/games認証

対応ゲーム

利用できるゲームの一覧です。各ゲームのスラッグは game パラメータに使えます。

レスポンスのフィールド

フィールド型説明
data[].idstringゲームID（UUID）。
data[].slugstringゲームのスラッグ。他のエンドポイントの game パラメータに使えます。
data[].namestringゲーム名。
data[].release_continuity_statusstring新しい製品の発売が続いているか。continuing、ended、unknown のいずれか。
data[].latest_release_date, data[].latest_release_title, data[].next_release_date, data[].next_release_titlestring | null直近と次回の発売日とタイトル。なければ null。
リクエスト例
curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/games"
レスポンス例
{
  "data": [
    {
      "id": "6f1d2c3b-4a59-4e8d-9c7b-1a2b3c4d5e6f",
      "slug": "one-piece-card-game",
      "name": "One Piece Card Game",
      "release_continuity_status": "continuing",
      "latest_release_date": "2026-09-26",
      "latest_release_title": "Booster Pack",
      "next_release_date": null,
      "next_release_title": null
    }
  ]
}
GET/sets認証

ゲーム別セット

セットの一覧を返します。ゲームごとに新しい順に並びます。game や language で絞り込み、limit と offset でページを送れます。

パラメータ

パラメータ型必須説明
gamestring任意pokemon、one-piece-card-game、yugioh などのカタログスラッグ。
languagestring任意セットに保存されている言語コード（en、ja など）。
limitinteger任意既定値は50です。1未満は1、200を超える値は200、数値以外は50として扱います。
offsetinteger任意0から始まる行オフセット。既定値は0です。

レスポンスのフィールド

フィールド型説明
data[].idstringセットID（UUID）。
data[].code, data[].namestringセットコードとセット名。
data[].release_datestring | null発売日（YYYY-MM-DD）。なければ null。
data[].game_slugstringゲームのスラッグ。他のエンドポイントの game パラメータに使えます。
data[].release_status, data[].catalog_statusstringrelease_status は unknown、announced、preorder、released、delayed、cancelled のいずれか。catalog_status はカードリストの充足度（partial、complete など）です。
data[].known_card_count, data[].expected_card_countinteger | nullこのセットのカタログ内のカード数と、想定されるカード数（不明なときは null）。
data[].metadataobjectシリーズや印刷総数などのセット情報。
paginationobjectlimit、offset、total、total_is_estimate（total が概算のときは true）。
リクエスト例
curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/sets?game=pokemon"
レスポンス例
{
  "data": [
    {
      "id": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d",
      "code": "EX-09",
      "name": "EXTRA BOOSTER VERSUS MONSTERS",
      "release_date": null,
      "game_slug": "digimon-card-game",
      "release_status": "released",
      "catalog_status": "complete",
      "known_card_count": 74,
      "expected_card_count": 74,
      "metadata": { "languageCode": "en" }
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 1,
    "total_is_estimate": false
  }
}
GET/sets/{setRef}認証

セット詳細

セットコードまたはIDでセットを1件返します。同じコードが複数のゲームにあるときは game を付けてください。

パラメータ

パラメータ型必須説明
setRefstring必須セットコードまたはセットID（EX-09 など）。存在しないセットは 404 set_not_found です。
gamestring任意セットコードが複数のゲームで重複する場合に指定するカタログスラッグ。

レスポンスのフィールド

フィールド型説明
data.idstringセットID（UUID）。
data.code, data.namestringセットコードとセット名。
data.release_datestring | null発売日（YYYY-MM-DD）。なければ null。
data.game_slugstringゲームのスラッグ。他のエンドポイントの game パラメータに使えます。
data.release_status, data.catalog_statusstringrelease_status は unknown、announced、preorder、released、delayed、cancelled のいずれか。catalog_status はカードリストの充足度（partial、complete など）です。
data.known_card_count, data.expected_card_countinteger | nullこのセットのカタログ内のカード数と、想定されるカード数（不明なときは null）。
data.metadataobjectシリーズや印刷総数などのセット情報。
リクエスト例
curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/sets/EX-09?game=digimon-card-game"
レスポンス例
{
  "data": {
    "id": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d",
    "code": "EX-09",
    "name": "EXTRA BOOSTER VERSUS MONSTERS",
    "release_date": null,
    "game_slug": "digimon-card-game",
    "release_status": "released",
    "catalog_status": "complete",
    "known_card_count": 74,
    "expected_card_count": 74,
    "metadata": { "languageCode": "en" }
  }
}

カードエンドポイント

GET/cards/{cardId}認証

カード詳細

カード1件の詳細を、最新価格、および他の言語やセットにある同じカードとの関連情報とあわせて返します。

Freeプランでは価格フィールドが空になります。価格を取得するには、HobbyistまたはBuilderにアップグレードしてください。

Hobbyist と Builder では、一部のカードについて価格データを提供します（提供がある場合）。価格データのないカードも多くあります。

パラメータ

パラメータ型必須説明
cardIdstring必須32文字の16進数、またはハイフン付きUUID。レスポンスのidは32文字の16進数です。
localestring任意翻訳テキストの優先ロケール（ja-JP など）。
languagestring任意翻訳テキストの優先言語（ja など）。

レスポンスのフィールド

フィールド型説明
data.idstringカードID（32文字の16進数）。
data.name, data.card_number, data.raritystringカード名、カード番号、レアリティ。
data.language_codestring言語コード（en、ja など）。
data.game_slug, data.game_namestringカードが属するゲーム。
data.set_code, data.set_namestring | nullカードが収録されたセット。
data.image_urlstring | nullカード画像のURL。
data.attributesobjectコスト、タイプ、カードテキストなど、ゲームごとの詳細。
data.game_id, data.set_idstringゲームIDとセットID。
data.created_at, data.updated_atstring作成日時と最終更新日時（ISO 8601）。
data.latest_pricesarray現在の価格。行の形式は「最新価格」と同じです。価格データは、データがある一部のカードのみが対象です。すべてのカードに価格があるわけではありません。
data.associationobject | null他の印刷とのつながり。print_count、sibling_count、available_language_codes、sibling_prints を含みます。
data.localizationsobject | null他言語のカードテキスト。resolved には指定したロケールまたは言語に最も合うものが入ります。
prices_includedbooleanプランに価格が含まれるときは true。
upgrade_hintstring | null価格が含まれないときの案内。含まれるときは null。
リクエスト例
curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/cards/97997e2be098df0ff51e0e945dda577a"
レスポンス例
{
  "data": {
    "id": "97997e2be098df0ff51e0e945dda577a",
    "game_id": "6f1d2c3b-4a59-4e8d-9c7b-1a2b3c4d5e6f",
    "set_id": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d",
    "name": "Abbadomon",
    "card_number": "EX9-055 R",
    "rarity": "r",
    "language_code": "en",
    "game_slug": "digimon-card-game",
    "game_name": "Digimon Card Game",
    "set_code": "EX-09",
    "set_name": "EXTRA BOOSTER VERSUS MONSTERS",
    "image_url": "https://images.tradingcardstudio.com/card-images/faa8f84b5d4e091fc3bf2257080f9c1600b9d10e13ab84f59113026a32845cdf.png",
    "attributes": { "cost": "11", "level": "Lv.6", "card_type": "Digimon" },
    "created_at": "2026-01-15T00:00:00.000Z",
    "updated_at": "2026-10-12T00:00:00.000Z",
    "latest_prices": [
      {
        "card_id": "97997e2be098df0ff51e0e945dda577a",
        "market": "US",
        "currency_code": "USD",
        "condition": null,
        "price_amount": "4.25",
        "price_type": "market",
        "source_variant": null,
        "mapping_scope": "exact_print",
        "captured_at": "2026-10-12T00:00:00.000Z",
        "updated_at": "2026-10-12T00:00:00.000Z"
    }
    ],
    "association": {
      "mapped": true,
      "card_concept_id": "ad759f77-32eb-501b-8aa5-5b5c7e15e2d0",
      "print_count": 2,
      "sibling_count": 1,
      "available_language_codes": ["en", "ja"],
      "sibling_prints": [
        { "card_print_id": "3c5e7a91-2b4d-4f6a-8c1e-9d0b2a4c6e81", "name": "アバドモン", "language_code": "ja", "card_number": "EX9-055" }
      ]
    },
    "localizations": {
      "requested_locale": "en-US",
      "requested_language": "en",
      "available": [
        { "source_kind": "official_print", "language_code": "en", "locale_code": "en-US", "fields": { "name": "Abbadomon" } },
        { "source_kind": "official_print", "language_code": "ja", "locale_code": "ja-JP", "fields": { "name": "アバドモン" } }
      ],
      "resolved": { "source_kind": "official_print", "language_code": "en", "locale_code": "en-US", "fields": { "name": "Abbadomon" } }
    }
  },
  "prices_included": true,
  "upgrade_hint": null
}
GET/cards/{cardId}/siblings認証

関連印刷

同じカードの他の印刷（他言語版や別セットの再録など）を返します。

パラメータ

パラメータ型必須説明
cardIdstring必須カードID。32文字の16進数、またはハイフン付きUUID。
localestring任意翻訳テキストの優先ロケール（ja-JP など）。
languagestring任意翻訳テキストの優先言語（ja など）。

レスポンスのフィールド

フィールド型説明
dataarray同じカードの他の印刷。形式は「カードコンセプト」の prints と同じです。
associationobject他の印刷とのつながり。card_concept_id、print_count、sibling_count、available_language_codes を含みます。
localizationsobject他言語のカードテキスト。resolved には指定したロケールまたは言語に最も合うものが入ります。
リクエスト例
curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/cards/97997e2be098df0ff51e0e945dda577a/siblings"
レスポンス例
{
  "data": [
    {
      "card_id": "97997e2be098df0ff51e0e945dda577a",
      "card_print_id": "3c5e7a91-2b4d-4f6a-8c1e-9d0b2a4c6e81",
      "card_concept_id": "ad759f77-32eb-501b-8aa5-5b5c7e15e2d0",
      "is_source": false,
      "name": "アバドモン",
      "card_number": "EX9-055",
      "language_code": "ja",
      "locale_code": "ja-JP",
      "rarity": "r",
      "variant_key": "base",
      "image_url": "https://images.tradingcardstudio.com/card-images/faa8f84b5d4e091fc3bf2257080f9c1600b9d10e13ab84f59113026a32845cdf.png",
      "set": {
        "id": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d",
        "code": "EX-09",
        "name": "エクストラブースター VERSUS MONSTERS",
        "release_date": null
      }
    }
  ],
  "association": {
    "mapped": true,
    "card_concept_id": "ad759f77-32eb-501b-8aa5-5b5c7e15e2d0",
    "source_card_print_id": "3c5e7a91-2b4d-4f6a-8c1e-9d0b2a4c6e81",
    "print_count": 2,
    "sibling_count": 1,
    "available_language_codes": ["en", "ja"],
    "available_locale_codes": ["en-US", "ja-JP"]
  },
  "localizations": {
    "requested_locale": "ja-JP",
    "requested_language": null,
    "available": [
      { "source_kind": "official_print", "language_code": "ja", "locale_code": "ja-JP", "fields": { "name": "アバドモン" } }
    ],
    "resolved": { "source_kind": "official_print", "language_code": "ja", "locale_code": "ja-JP", "fields": { "name": "アバドモン" } }
  }
}
GET/cards/{cardId}/localizations認証

カードの言語データ

カード名とテキストを他の言語で返します。指定した言語に最も合うものも含まれます。

パラメータ

パラメータ型必須説明
cardIdstring必須カードID。32文字の16進数、またはハイフン付きUUID。
localestring任意翻訳テキストの優先ロケール（ja-JP など）。
languagestring任意翻訳テキストの優先言語（ja など）。

レスポンスのフィールド

フィールド型説明
data.requested_locale, data.requested_languagestring | nullresolved の選択に使ったロケールと言語。
data.availablearray利用できるすべての言語データ。各要素に language_code、locale_code、fields があります。
data.resolvedobject | null指定したロケールまたは言語に最も合うもの。なければ null。
associationobject他の印刷とのつながり。card_concept_id、print_count、sibling_count、available_language_codes を含みます。
リクエスト例
curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/cards/97997e2be098df0ff51e0e945dda577a/localizations"
レスポンス例
{
  "data": {
    "requested_locale": "ja-JP",
    "requested_language": null,
    "available": [
      { "source_kind": "official_print", "language_code": "ja", "locale_code": "ja-JP", "fields": { "name": "アバドモン" } }
    ],
    "resolved": { "source_kind": "official_print", "language_code": "ja", "locale_code": "ja-JP", "fields": { "name": "アバドモン" } }
  },
  "association": {
    "mapped": true,
    "card_concept_id": "ad759f77-32eb-501b-8aa5-5b5c7e15e2d0",
    "source_card_print_id": "3c5e7a91-2b4d-4f6a-8c1e-9d0b2a4c6e81",
    "print_count": 2,
    "sibling_count": 1,
    "available_language_codes": ["en", "ja"],
    "available_locale_codes": ["en-US", "ja-JP"]
  }
}
GET/cards/{cardId}/prices認証

最新価格

カード1件の最新価格を返します。IDにはカードIDと印刷IDのどちらも使えます。

Freeプランでは価格フィールドが空になります。価格を取得するには、HobbyistまたはBuilderにアップグレードしてください。

Hobbyist と Builder では、一部のカードについて価格データを提供します（提供がある場合）。価格データのないカードも多くあります。

パラメータ

パラメータ型必須説明
cardIdstring必須カードIDまたは印刷ID。32文字の16進数、またはハイフン付きUUID。
marketstring任意US、EU、JAPAN、JP のいずれか。JP は JAPAN と同じ市場です。省略するとすべての市場を返します。未知の値は 400 invalid_market です。
conditionstring任意省略するとニアミント（NM）または未鑑定の価格を返します。NM、S、A、A-、B、C、D、PL、PSA10 や BGS9.5 のようなグレード、all も使えます。未知の値は 400 invalid_condition です。

レスポンスのフィールド

フィールド型説明
data[].card_idstringカードID（32文字の16進数）。
data[].marketstringUS、EU、JAPAN のいずれか。
data[].currency_codestring通貨（USD、EUR、JPY など）。
data[].price_amountstring価格（小数の文字列）。価格データは、データがある一部のカードのみが対象です。すべてのカードに価格があるわけではありません。
data[].price_typestringmarket、low、mid、high のいずれか。
data[].conditionstring | nullニアミント（NM）または未鑑定のときは null。それ以外は A や PSA:10 などの状態。
data[].grader, data[].gradestring鑑定済みの行のみ。例: PSA と 10。
data[].source_variantstring | nullholofoil などの仕上げ。なければ null。
data[].mapping_scopestring価格の対象範囲。exact_print（この印刷）、shared_across_variants（すべての仕上げ）、listing_aggregate（現在の出品）、sale_aggregate（最近の取引）など。
data[].price_min, data[].price_max, data[].price_median, data[].sample_count, data[].regionmixedlisting_aggregate と sale_aggregate の行のみ。価格の範囲、中央値、件数、地域（jp または us）。
data[].last_sale_price, data[].last_sale_on, data[].window_daysmixedsale_aggregate の行のみ。直近の取引価格と日付、対象期間の日数。
data[].captured_at, data[].updated_atstring価格を記録した日時と最終更新日時。
prices_includedbooleanプランに価格が含まれるときは true。
upgrade_hintstring | null価格が含まれないときの案内。含まれるときは null。
リクエスト例
curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/cards/97997e2be098df0ff51e0e945dda577a/prices"
レスポンス例
{
  "data": [
    {
      "card_id": "97997e2be098df0ff51e0e945dda577a",
      "market": "US",
      "currency_code": "USD",
      "condition": null,
      "price_amount": "4.25",
      "price_type": "market",
      "source_variant": null,
      "mapping_scope": "exact_print",
      "captured_at": "2026-10-12T00:00:00.000Z",
      "updated_at": "2026-10-12T00:00:00.000Z"
    }
  ],
  "prices_included": true,
  "upgrade_hint": null
}
GET/concepts/{conceptId}認証

カードコンセプト

1種類のカード（コンセプト）を、そのすべての印刷と他言語のテキストとあわせて返します。

パラメータ

パラメータ型必須説明
conceptIdstring必須コンセプトID。concept.id や association.card_concept_id で返る値です。
localestring任意翻訳テキストの優先ロケール（ja-JP など）。
languagestring任意翻訳テキストの優先言語（ja など）。

レスポンスのフィールド

フィールド型説明
data.idstringコンセプトID。
data.name, data.concept_typestringカード名とコンセプトの種類。
data.game_slug, data.game_namestringカードが属するゲーム。
data.printsarrayこのカードのすべての印刷。card_id、card_print_id、番号、言語、レアリティ、画像、セットを含みます。
data.localizationsobject他言語のカードテキスト。resolved には指定したロケールまたは言語に最も合うものが入ります。
associationobject他の印刷とのつながり。card_concept_id、print_count、sibling_count、available_language_codes を含みます。
リクエスト例
curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/concepts/ad759f7732eb501b8aa55b5c7e15e2d0"
レスポンス例
{
  "data": {
    "id": "ad759f77-32eb-501b-8aa5-5b5c7e15e2d0",
    "game_slug": "digimon-card-game",
    "game_name": "Digimon Card Game",
    "name": "Abbadomon",
    "concept_type": "card",
    "prints": [
      {
        "card_id": "97997e2be098df0ff51e0e945dda577a",
        "card_print_id": "3c5e7a91-2b4d-4f6a-8c1e-9d0b2a4c6e81",
        "card_concept_id": "ad759f77-32eb-501b-8aa5-5b5c7e15e2d0",
        "is_source": false,
        "name": "アバドモン",
        "card_number": "EX9-055",
        "language_code": "ja",
        "locale_code": "ja-JP",
        "rarity": "r",
        "variant_key": "base",
        "image_url": "https://images.tradingcardstudio.com/card-images/faa8f84b5d4e091fc3bf2257080f9c1600b9d10e13ab84f59113026a32845cdf.png",
        "set": {
          "id": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d",
          "code": "EX-09",
          "name": "エクストラブースター VERSUS MONSTERS",
          "release_date": null
        }
      }
    ],
    "localizations": {
      "available": [
        { "source_kind": "official_print", "language_code": "ja", "locale_code": "ja-JP", "fields": { "name": "アバドモン" } }
      ],
      "resolved": null
    }
  },
  "association": {
    "mapped": true,
    "card_concept_id": "ad759f77-32eb-501b-8aa5-5b5c7e15e2d0",
    "source_card_print_id": "3c5e7a91-2b4d-4f6a-8c1e-9d0b2a4c6e81",
    "print_count": 2,
    "sibling_count": 1,
    "available_language_codes": ["en", "ja"],
    "available_locale_codes": ["en-US", "ja-JP"]
  }
}
GET/prints/{cardPrintId}認証

印刷詳細

物理的な印刷1件を、セット、番号、レアリティ、画像、ゲームごとの詳細とあわせて返します。include=current_prices を付けると現在の価格も返ります。

Freeプランでは価格フィールドが空になります。価格を取得するには、HobbyistまたはBuilderにアップグレードしてください。

Hobbyist と Builder では、一部のカードについて価格データを提供します（提供がある場合）。価格データのないカードも多くあります。

パラメータ

パラメータ型必須説明
cardPrintIdstring必須印刷ID。32文字の16進数、またはハイフン付きUUID。
includestring任意current_prices を渡すと現在の価格を追加します。それ以外の値は 400 invalid_include です。
conditionstring任意include=current_prices の価格を絞り込みます。値は「最新価格」の condition と同じです。

レスポンスのフィールド

フィールド型説明
data.idstring印刷ID（UUID）。
data.concept_idstringこの印刷が属するカード（コンセプト）のID。「カードコンセプト」で使えます。
data.game_id, data.set_idstringゲームIDとセットID。
data.language_code, data.locale_codestring言語とロケール（ja と ja-JP など）。
data.gameobjectゲームのスラッグと名前。
data.setobject | nullセットのコード、名前、シリーズ、発売日。なければ null。
data.card_metadataobjectカード番号、タイトル、レアリティ、バリアント、画像。ポケモンの印刷には、HP、タイプ、ワザなどを含む pokemon も入ります。
data.pricing_metadataobjectas_of（最新の価格日）、products（範囲と仕上げごとの価格。include=current_prices のときに入ります）、history_url（「印刷価格」へのパス）。価格データは、データがある一部のカードのみが対象です。すべてのカードに価格があるわけではありません。
data.created_at, data.updated_atstring作成日時と最終更新日時（ISO 8601）。
prices_includedbooleanプランに価格が含まれるときは true。
upgrade_hintstring | null価格が含まれないときの案内。含まれるときは null。
リクエスト例
curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/prints/{cardPrintId}?include=current_prices"
レスポンス例
{
  "data": {
    "id": "3c5e7a91-2b4d-4f6a-8c1e-9d0b2a4c6e81",
    "game_id": "6f1d2c3b-4a59-4e8d-9c7b-1a2b3c4d5e6f",
    "set_id": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d",
    "concept_id": "ad759f77-32eb-501b-8aa5-5b5c7e15e2d0",
    "language_code": "en",
    "locale_code": "en-US",
    "game": { "slug": "digimon-card-game", "name": "Digimon Card Game" },
    "set": { "code": "EX-09", "name": "EXTRA BOOSTER VERSUS MONSTERS", "series": null, "release_date": null },
    "card_metadata": {
      "number": { "printed": "EX9-055", "set_total": null, "display": "EX9-055" },
      "title": "Abbadomon",
      "rarity": { "key": "r", "name": "r", "short_code": null },
      "variant": "base",
      "images": { "primary": "https://images.tradingcardstudio.com/card-images/faa8f84b5d4e091fc3bf2257080f9c1600b9d10e13ab84f59113026a32845cdf.png", "small": null },
      "pokemon": null
    },
    "pricing_metadata": {
      "as_of": "2026-10-12",
      "products": [
        {
          "mapping_status": "verified",
          "mapping_scope": "exact_print",
          "variants": [
            {
              "variant": "default",
              "condition": null,
              "market": "US",
              "currency": "USD",
              "prices": { "market": "4.25" },
              "observed_on": "2026-10-12",
              "captured_at": "2026-10-12T00:00:00.000Z",
              "updated_at": "2026-10-12T00:00:00.000Z"
            }
          ]
        }
      ],
      "history_url": "/v1/prints/3c5e7a91-2b4d-4f6a-8c1e-9d0b2a4c6e81/prices"
    },
    "created_at": "2026-01-15T00:00:00.000Z",
    "updated_at": "2026-10-12T00:00:00.000Z"
  },
  "prices_included": true,
  "upgrade_hint": null
}
GET/prints/{cardPrintId}/prices認証

印刷価格

印刷1件の最新価格を返します。

Freeプランでは価格フィールドが空になります。価格を取得するには、HobbyistまたはBuilderにアップグレードしてください。

Hobbyist と Builder では、一部のカードについて価格データを提供します（提供がある場合）。価格データのないカードも多くあります。

パラメータ

パラメータ型必須説明
cardPrintIdstring必須印刷ID。32文字の16進数、またはハイフン付きUUID。
marketstring任意US、EU、JAPAN、JP のいずれか。JP は JAPAN と同じ市場です。省略するとすべての市場を返します。未知の値は 400 invalid_market です。
conditionstring任意省略するとニアミント（NM）または未鑑定の価格を返します。NM、S、A、A-、B、C、D、PL、PSA10 や BGS9.5 のようなグレード、all も使えます。未知の値は 400 invalid_condition です。
price_typestring任意価格の種類（market、low、mid、high など）で絞り込みます。

レスポンスのフィールド

フィールド型説明
data[].card_print_idstring印刷ID（UUID）。
data[].marketstringUS、EU、JAPAN のいずれか。
data[].currency_codestring通貨（USD、EUR、JPY など）。
data[].price_amountstring価格（小数の文字列）。価格データは、データがある一部のカードのみが対象です。すべてのカードに価格があるわけではありません。
data[].price_typestringmarket、low、mid、high のいずれか。
data[].conditionstring | nullニアミント（NM）または未鑑定のときは null。それ以外は A や PSA:10 などの状態。
data[].grader, data[].gradestring鑑定済みの行のみ。例: PSA と 10。
data[].source_variantstring | nullholofoil などの仕上げ。なければ null。
data[].mapping_scopestring価格の対象範囲。exact_print（この印刷）、shared_across_variants（すべての仕上げ）、listing_aggregate（現在の出品）、sale_aggregate（最近の取引）など。
data[].price_min, data[].price_max, data[].price_median, data[].sample_count, data[].regionmixedlisting_aggregate と sale_aggregate の行のみ。価格の範囲、中央値、件数、地域（jp または us）。
data[].last_sale_price, data[].last_sale_on, data[].window_daysmixedsale_aggregate の行のみ。直近の取引価格と日付、対象期間の日数。
data[].observed_onstring価格の対象日。
data[].captured_at, data[].updated_atstring価格を記録した日時と最終更新日時。
prices_includedbooleanプランに価格が含まれるときは true。
upgrade_hintstring | null価格が含まれないときの案内。含まれるときは null。
リクエスト例
curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/prints/{cardPrintId}/prices"
レスポンス例
{
  "data": [
    {
      "card_print_id": "3c5e7a91-2b4d-4f6a-8c1e-9d0b2a4c6e81",
      "market": "US",
      "currency_code": "USD",
      "condition": null,
      "price_amount": "4.25",
      "price_type": "market",
      "source_variant": null,
      "mapping_scope": "exact_print",
      "observed_on": "2026-10-12",
      "captured_at": "2026-10-12T00:00:00.000Z",
      "updated_at": "2026-10-12T00:00:00.000Z"
    }
  ],
  "prices_included": true,
  "upgrade_hint": null
}

コード例

カードを検索
curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/cards?game=pokemon&limit=25&offset=0"
最新価格を読む
curl -H "X-API-Key: tv_live_your_key_here" \
     "https://api.tradingcardstudio.com/v1/cards/97997e2be098df0ff51e0e945dda577a/prices"

エラー処理

400
不正なリクエスト
不正なJSON、またはルートが拒否したクエリ。価格ルートでは、未知の condition は error invalid_condition、未知の market は error invalid_market を返します。
401
未認証
有効なAPIキーがないカタログ呼び出しは、401 と error unauthorized を返します。ダッシュボードでキーを作り、X-API-Key で送ってください。
403
権限なし
価格ルートは、プランに価格がないことを理由に403を返しません。Freeは価格フィールドが空で prices_included が false の200を返します。
404
見つからない
存在しないセットは error set_not_found を返します。
429
リクエスト過多
アカウントが月次のカタログ上限を使い切っています。ボディの error は rate_limited、message は「This account has used its monthly catalog request allowance.」です。Retry-After は次のUTC月1日 00:00 までの秒数です。その秒数だけ待ってから再度呼び出してください。429も上限に計上されます。

ベストプラクティス

絞り込みを先に

ページサイズを上げる前に game、setCode、q を送ってください。

画像をキャッシュ

各カードの image_url を使います。このページのサンプルは https://images.tradingcardstudio.com です。