TypeScript npm Node 18+ / Browser / CF Workers / Bun / Deno
JavaScript & TypeScript SDK
ネイティブfetch使用のゼロ依存SDK。ESM + CJSデュアル出力、本番APIのシェイプに対する完全なTypeScript型定義付き。
インストール npm
$ npm install @tcgpricelookup/sdk主な機能
ゼロ依存
ネイティブfetchを使用 — axios、node-fetch、不要なライブラリは一切なし。
ESM + CJS
デュアルパッケージ出力。どんなバンドラーやrequire()でも動作。
ユニバーサルランタイム
Node 18+、ブラウザ、Cloudflare Workers、Bun、Deno対応。
型付きエラー
AuthenticationError、PlanAccessError、RateLimitError — instanceofで処理可能。
自動バッチチャンク
任意の数のIDを渡すと — SDKが20ID以下のチャンクに自動分割。
バックオフ付き自動リトライ
429および5xxに対するオプションの指数バックオフによる自動リトライ。
クイックスタート
quickstart.ts TypeScript
import { TcgLookupClient } from "@tcgpricelookup/sdk";
// クライアントを初期化
const tcg = new TcgLookupClient({ apiKey: process.env.TCG_API_KEY! });
// カードを検索
const res = await tcg.cards.search({ q: "charizard", game: "pokemon", limit: 20 });
console.log(res.data[0].name); // "Charizard ex"
// 特定のカードを完全な価格データで取得
const card = await tcg.cards.get("019535a1-d5d0-7c12-a3e8-b7f4c6d8e9a2");
console.log(card.prices.raw.near_mint?.tcgplayer?.market); // 例: 4.25
console.log(card.prices.graded?.psa?.["10"]?.ebay?.avg_7d); // Trader+
// リクエスト後にレートリミットの状態を確認
console.log(tcg.rateLimit); // { limit: 100000, remaining: 99987 }APIインターフェース
tcg.cards.search(params) 検索・一括検索
// キーワード検索とフィルター
const res = await tcg.cards.search({ q: "charizard", game: "pokemon", set: "obsidian-flames", limit: 20 });
// IDによる一括検索 — 20件を超えると自動チャンク
const portfolio = ["uuid1", "uuid2", /* ...100+ IDs */];
const { data } = await tcg.cards.search({ ids: portfolio }); tcg.cards.get(id) 完全な価格内訳付きの単一カード
const card = await tcg.cards.get("019535a1-d5d0-7c12-a3e8-b7f4c6d8e9a2");
console.log(card.name, card.set.name, card.game);
console.log(card.prices.raw.near_mint?.tcgplayer?.market);
console.log(card.prices.raw.near_mint?.ebay?.avg_7d); tcg.cards.history(id, params) Trader+以上が必要
const history = await tcg.cards.history(card.id, { period: "30d" });
// history.data: array of { date, near_mint: { tcgplayer: { market } } } tcg.sets.list(params) すべてのセットを閲覧
const sets = await tcg.sets.list({ game: "pokemon", limit: 10 });
// sets.data[0]: { id, name, series, released_at, card_count } tcg.games.list() 対応する8ゲームすべて
const games = await tcg.games.list();
// ['pokemon', 'mtg', 'yugioh', 'lorcana', 'onepiece', ...]エラーハンドリング
error-handling.ts TypeScript
import { TcgLookupClient, AuthenticationError, PlanAccessError, RateLimitError } from "@tcgpricelookup/sdk";
try {
const card = await tcg.cards.get("some-id");
} catch (err) {
if (err instanceof AuthenticationError) {
console.error("APIキーが無効です");
} else if (err instanceof PlanAccessError) {
console.error("価格履歴にはTrader+へのアップグレードが必要です");
} else if (err instanceof RateLimitError) {
console.error(`レートリミット。${ err.retryAfter }秒後に再試行してください`);
}
}AuthenticationError APIキーが無効または未指定 (401)
PlanAccessError 上位プランが必要な機能 (403)
RateLimitError リクエスト数超過。.retryAfterプロパティあり (429)
NotFoundError カードまたはリソースが見つからない (404)
レートリミットヘッダー
rate-limits.ts
// リクエスト後、クライアントは最後のレートリミットヘッダーをキャッシュします
await tcg.cards.search({ q: "pikachu" });
console.log(tcg.rateLimit);
// { limit: 100000, remaining: 99987, reset: 1712000000 }設定オプション
config.ts
const tcg = new TcgLookupClient({
apiKey: process.env.TCG_API_KEY!,
retry: { maxAttempts: 3, initialDelay: 500 }, // オプション: 429/5xxのリトライ
baseUrl: "https://api.tcgpricelookup.com/v1", // オプション: テスト用のオーバーライド
});リンク
JavaScriptで開発を始めよう
無料APIキーを取得して、数分でカード価格のクエリを開始しましょう。