API Documentation
Learn how to integrate the JustTCG API into your applications.
Overview
The JustTCG API provides real-time pricing data for trading card games including Magic: The Gathering, Pokémon, Yu-Gi-Oh!, Disney Lorcana, One Piece TCG, Digimon, and Union Arena. Our API is designed to be simple, fast, and reliable.
Notice: The card-search and variants endpoints are deprecated and will be phased out over time. Please migrate to the cards endpoint, which now supports both searching and direct lookups. This change is part of our effort to provide a more intuitive and seamless API experience. For most use-cases, you only need to use the games, sets, and cards endpoints.
Base URL
https://api.justtcg.com/v1
Authentication
All API requests require authentication using an API key. You can obtain an API key by signing up for an account and subscribing to a plan.
API Key Authentication
Include your API key in the request headers:
x-api-key:tcg_your_api_key_here
API Reference
API Architecture Update: Our API is now focused on three main endpoints for a more intuitive and seamless experience:
- Games and Sets: For discovering available games and sets.
- Cards: For searching and direct lookups. If you pass an
id
, you get a direct lookup. If you do not pass anid
, the endpoint serves as a flexible search.
Collection Resources
These endpoints provide information about the available trading card games and sets in our database. Start with these endpoints to understand what's available before diving into the cards
endpoint.
Games
Retrieve a list of all games.
https://api.justtcg.com/v1/games
Response Object
Sets
Retrieve a list of all sets.
https://api.justtcg.com/v1/sets
Query Parameters
Response Object
Cards
This high-performance endpoint provides rapid access to card data whether you already have identifier values or not. For the best performance when retrieving specific cards, use this endpoint with IDs obtained from the games
or sets
endpoints.
Card Lookup
Retrieve a card and its variant prices by ID or search query. You can optionally filter the returned variants by condition and printing type.
https://api.justtcg.com/v1/cards
Note: The tcgplayerId
, cardId
or variantId
will take precedence over any search query if any of those are provided.
Query Parameters
Response Object
Batch Card Lookup
Retrieve multiple cards and their variants in a single request. For each card, you can optionally filter variants by specifying condition and printing parameters.
https://api.justtcg.com/v1/cards
Request Body Parameters
Send an array of objects, each containing the following properties:
Response Object
Card Object
The Card object contains detailed information about a trading card, including its variants with pricing information.
Variant Object
Each variant represents a specific combination of condition and printing for a card, with its associated price.
Example Card Object
{
"id": "pokemon-battle-academy-fire-energy-22-charizard-stamped",
"name": "Fire Energy (#22 Charizard Stamped)",
"game": "Pokemon",
"set": "Battle Academy",
"number": "N/A",
"tcgplayerId": "219042",
"rarity": "Promo",
"details": null,
"variants": [
{
"id": "pokemon-battle-academy-fire-energy-22-charizard-stamped_near-mint",
"printing": "Normal",
"condition": "Near Mint",
"price": 4.99,
"lastUpdated": 1743100261
},
{
"id": "pokemon-battle-academy-fire-energy-22-charizard-stamped_lightly-played",
"printing": "Normal",
"condition": "Lightly Played",
"price": 3.50,
"lastUpdated": 1743101175
}
]
}
Card IDs
Each card object has a unique id
, sometimes referred to as the cardId
or "Card ID".
The card ID is structured as game-set-name
. This ID can be used for direct lookups using the /cards
endpoint.
Note: Multiple variants of the same card ID may exist, each with its own unique variant ID. The card ID is not guaranteed to be unique across all variants.
Variant IDs
Each variant has a unique id
, sometimes referred to as variantId
or "Variant ID".
The variant ID is structured as cardId_condition_printing
and can be used for direct, high-performance lookups using the /cards
endpoint.
If you already have the variant ID, using it directly is the fastest way to retrieve pricing information.
Filtering Variants
When retrieving cards, you can filter the variants by adding optional printing
and condition
parameters to your requests. This helps reduce response size and narrow down results to specific variants you're interested in.
Consistency Note
All endpoints that return card data use this same structure. Every card will have at least one variant in its variants array.
Response Format
All API responses follow a consistent format with a data
field containing the requested information, a meta
field with pagination details (when applicable), and a _metadata
field with API usage statistics.
Response Structure
Error Handling
The JustTCG API uses standard HTTP status codes and returns consistent error response formats to help you quickly identify and resolve issues.
HTTP Status Codes
Error Response Format
All error responses follow a consistent format with an error
object containing details about the error.
{
"error": "Invalid game parameter. Must be one of: magic-the-gathering, mtg, pokemon, yugioh, age-of-sigmar, warhammer-40000, union-arena, flesh-and-blood-tcg, disney-lorcana, digimon-card-game, one-piece-card-game",
"code": "INVALID_REQUEST"
}
Common Error Codes
Code Examples
Practical examples showing how to integrate the JustTCG API in real-world scenarios.
// Set your API key
const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://api.justtcg.com/v1';
// Fetch all cards from a set (automatically handles pagination)
async function updatePricesForSet(gameId, setId) {
console.log(`Updating prices for ${gameId} set: ${setId}...`);
let allCards = [];
let hasMoreResults = true;
let offset = 0;
const LIMIT = 20;
// Keep fetching until we've got all cards
while (hasMoreResults) {
try {
// Create URL with query parameters
const url = new URL(`${BASE_URL}/cards`);
url.searchParams.append('game', gameId);
url.searchParams.append('set', setId);
url.searchParams.append('limit', LIMIT);
url.searchParams.append('offset', offset);
// Make the API request
const response = await fetch(url, {
headers: { 'X-API-Key': API_KEY }
});
const result = await response.json();
if (!response.ok) {
throw new Error(result.error?.message || 'API request failed');
}
const cards = result.data;
console.log(`Fetched ${cards.length} cards (offset: ${offset})`);
// Add cards to our collection
allCards = [...allCards, ...cards];
// Check if we've reached the end
hasMoreResults = cards.length === LIMIT;
offset += LIMIT;
// For demo purposes, just log first card's variants
if (offset === LIMIT && cards.length > 0) {
console.log('Sample card variation prices:');
cards[0].variants.forEach(v => {
console.log(`- ${v.condition} / ${v.printing}: $${v.price}`);
});
}
} catch (error) {
console.error('Error fetching cards:', error);
break;
}
}
console.log(`✅ Updated prices for ${allCards.length} cards`);
return allCards;
}
// Example usage
updatePricesForSet('magic-the-gathering', 'Modern Horizons 2');
// Set your API key
const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://api.justtcg.com/v1';
// Display a product page with multiple cards
async function fetchProductPageCards(cardIds) {
console.log('Fetching data for product display...');
try {
// Batch card lookup for efficiency
const response = await fetch(`${BASE_URL}/cards`, {
method: 'POST',
headers: {
'X-API-Key': API_KEY,
'Content-Type': 'application/json'
},
body: JSON.stringify(cardIds.map(id => ({ tcgplayerId: id })))
});
const result = await response.json();
if (!response.ok) {
throw new Error(result.error?.message || 'Failed to fetch cards');
}
// Display the cards (in a real app, you'd render these to the DOM)
console.log(`Displaying ${result.data.length} cards:`);
result.data.forEach(card => {
console.log(`${card.name} - ${card.set}`);
// Get the lowest price for display
const lowestPrice = Math.min(
...card.variants.map(v => v.price)
);
console.log(` Starting from: $${lowestPrice.toFixed(2)}`);
});
return result.data;
} catch (error) {
console.error('Error fetching product data:', error);
return [];
}
}
// Example usage
fetchProductPageCards(['219042', '25788', '1369']);
// Set your API key
const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://api.justtcg.com/v1';
// Calculate shopping cart total with specific variants
async function calculateShoppingCart(cartItems) {
console.log('Calculating shopping cart total...');
try {
// Get up-to-date prices for all variants in cart
const response = await fetch(`${BASE_URL}/cards`, {
method: 'POST',
headers: {
'X-API-Key': API_KEY,
'Content-Type': 'application/json'
},
body: JSON.stringify(cartItems)
});
const result = await response.json();
if (!response.ok) {
throw new Error(result.error?.message || 'Failed to fetch prices');
}
// Calculate total (in a real app, you'd update the cart UI)
let total = 0;
result.data.forEach(item => {
const subtotal = item.variants[0].price;
total += subtotal;
console.log(
`${item.name} (${item.variants[0].condition}, ${item.variants[0].printing}): $${item.variants[0].price.toFixed(2)}`
);
});
console.log(`Cart Total: $${total.toFixed(2)}`);
return total;
} catch (error) {
console.error('Error calculating cart:', error);
return 0;
}
}
// Example usage
calculateShoppingCart([
{ tcgplayerId: '219042', condition: 'Near Mint', printing: 'Normal' },
{ tcgplayerId: '25788', condition: 'Lightly Played', printing: '1st Edition' }
]);
Rate Limits & Usage
The JustTCG API has rate limits based on your subscription plan. You can monitor your API usage in your dashboard.
Rate Limits by Plan
429 Too Many Requests
response. If you exceed your monthly limit, you'll need to upgrade your plan to continue using the API.Reset Times: Daily rate limits reset at midnight (00:00) UTC. Monthly usage limits reset on the first day of each billing cycle at midnight (00:00) UTC.
Support
If you have any questions or need help with the API, please contact our support team.