Định dạng response

Tài liệu tham khảo đầy đủ về cấu trúc response JSON, phân trang và kiểu dữ liệu của TCG Price Lookup API.

Cấu trúc response cơ bản

Tất cả response API có cấu trúc JSON nhất quán:

{
  "data": [...],      // Mảng các đối tượng thẻ
  "total": 150,       // Tổng số kết quả khớp
  "limit": 20,        // Số kết quả được trả về
  "offset": 0,        // Offset phân trang
  "game": "pokemon"   // Ngữ cảnh trò chơi
}

Đối tượng thẻ

{
  "id": "pokemon-sv4-charizard-ex-006",
  "name": "Charizard ex",
  "game": "pokemon",
  "number": "006",
  "rarity": "Special Illustration Rare",
  "foil": false,
  "set": {
    "id": "sv4",
    "name": "Obsidian Flames",
    "code": "sv4",
    "releaseDate": "2023-08-11",
    "totalCards": 230
  },
  "images": {
    "small": "https://cdn.tcgpricelookup.com/images/pokemon/sv4/006_small.jpg",
    "large": "https://cdn.tcgpricelookup.com/images/pokemon/sv4/006_large.jpg"
  },
  "prices": {
    "nearMint": {
      "market": 285.00,
      "tcgplayer": 280.00,
      "ebay": 290.00,
      "low": 250.00,
      "high": 350.00
    },
    "lightlyPlayed": {
      "market": 240.00,
      "tcgplayer": 235.00,
      "ebay": 245.00
    },
    "moderatelyPlayed": { "market": 200.00 },
    "heavilyPlayed": { "market": 160.00 },
    "damaged": { "market": 100.00 }
  },
  "updatedAt": "2026-04-10T14:32:00Z"
}

Tình trạng thẻ

Tình trạng	Mô tả
`nearMint`	Near Mint — Không có vết trầy xước đáng chú ý
`lightlyPlayed`	Lightly Played — Vết xước nhẹ
`moderatelyPlayed`	Moderately Played — Vết xước rõ ràng
`heavilyPlayed`	Heavily Played — Hư hỏng đáng kể
`damaged`	Damaged — Hư hỏng nghiêm trọng

Đối tượng thẻ đã chấm điểm (Gói Trader trở lên)

{
  "id": "pokemon-base1-4",
  "graded": {
    "psa": {
      "10": { "market": 12000.00, "population": 128 },
      "9": { "market": 3500.00, "population": 342 },
      "8": { "market": 1200.00 }
    },
    "bgs": {
      "10": { "market": 25000.00 },
      "9.5": { "market": 8000.00 },
      "9": { "market": 4000.00 }
    },
    "cgc": {
      "10": { "market": 5000.00 },
      "9.5": { "market": 2500.00 }
    }
  }
}

Phân trang

Sử dụng tham số limit và offset cho tập kết quả lớn:

// Trang đầu tiên
const page1 = await tcg.search('charizard', { limit: 20, offset: 0 });

// Trang tiếp theo
const page2 = await tcg.search('charizard', { limit: 20, offset: 20 });

// Tính tổng số trang
const totalPages = Math.ceil(page1.total / 20);

Đơn vị giá

Tất cả giá là số thực dấu phẩy động tính bằng USD (đô la Mỹ):

"market": 285.00  // $285.00 USD