Skip to content
TCGdex logo TCGdex logo TCGdex API

The JavaScript SDK

NPM VersionGithub starsNPM DownloadsCoverageBuild Status

Installation

Section titled “Installation”
Terminal window
npm i @tcgdex/sdk

Basic Usage

Section titled “Basic Usage”
// Import the SDK in ESM/TypeScript
import TCGdex from '@tcgdex/sdk'


// OR import the SDK in CommonJS
const TCGdex = require('@tcgdex/sdk').default


// Instantiate the SDK with your preferred language
const tcgdex = new TCGdex('en');


// Use in an async context
(async () => {
  // Retrieve Furret from the Darkness Ablaze Set
  const card = await tcgdex.card.get('swsh3-136');
  console.log(card.name); // "Furret"
})();

Fetching Data

Section titled “Fetching Data”

The SDK provides dedicated endpoints for common data types:

// Get a specific card
const card = await tcgdex.card.get('swsh3-136');


// Get a specific set
const set = await tcgdex.set.get('swsh3');


// Get a specific serie
const serie = await tcgdex.serie.get('swsh');


// Get a list of all cards
const allCards = await tcgdex.card.list();

Getting Random Data

Section titled “Getting Random Data”

You can also retrieve random cards, sets, or series:

// Get a random card
const randomCard = await tcgdex.random.card();


// Get a random set
const randomSet = await tcgdex.random.set();


// Get a random serie
const randomSerie = await tcgdex.random.serie();

Advanced Queries

Section titled “Advanced Queries”

The SDK provides a powerful query system to filter data:

import TCGdex, { Query } from '@tcgdex/sdk';


const tcgdex = new TCGdex('en');


// Create a query to find Pikachu cards with HP between 60 and 70
const pikachuCards = await tcgdex.card.list(
  Query.create()
    .equal('name', 'Pikachu')  // Match exact name
    .greaterOrEqualThan('hp', 60)  // HP >= 60
    .lesserThan('hp', 70)  // HP < 70
    .sort('localId', 'ASC')  // Sort by ID ascending
);


// Find cards containing "5" in their ID but not "tg"
const filteredCards = await tcgdex.card.list(
  Query.create()
    .contains('localId', '5')  // ID contains "5"
    .not.contains('localId', 'tg')  // ID doesn't contain "tg"
);


// Pagination example - get page 3 with 2 items per page
const paginatedCards = await tcgdex.card.list(
  Query.create()
    .paginate(3, 2)
);

Object Relationships

Section titled “Object Relationships”

The SDK makes it easy to navigate relationships between objects:

// Get a card then retrieve its set
const card = await tcgdex.card.get('swsh3-136');
const set = await card.getSet();


// Get a set then retrieve its serie
const set = await tcgdex.set.get('swsh3');
const serie = await set.getSerie();


// Get a card from a set's card list
const set = await tcgdex.set.get('swsh3');
const firstCardResume = set.cards[0];
const fullCard = await firstCardResume.getCard();

Filtering by Attributes

Section titled “Filtering by Attributes”

Find cards by specific attributes:

// Get all fire type cards
const fireType = await tcgdex.type.get('fire');


// Get all cards with specific HP
const hp90Cards = await tcgdex.hp.get('90');


// Get all cards by a specific illustrator
const illustratorCards = await tcgdex.illustrator.get('TOKIYA');


// Get all cards with a specific rarity
const rareCards = await tcgdex.rarity.get('rare');

Configuration Options

Section titled “Configuration Options”

The SDK provides several configuration options:

// Create SDK with a specific language
const tcgdex = new TCGdex('fr');  // French


// Change the language after initialization
tcgdex.setLang('en');  // Switch to English


// Set a custom API endpoint
tcgdex.setEndpoint('https://custom-api.example.com/v2');


// Configure caching
tcgdex.setCacheTTL(3600);  // Set cache duration to 1 hour

Card Images

Section titled “Card Images”

Access card images easily:

const card = await tcgdex.card.get('swsh3-136');


// Get high-quality PNG image URL
const highQualityPng = card.getImageURL('high', 'png');


// Get low-quality WEBP image URL for performance
const lowQualityWebp = card.getImageURL('low', 'webp');
Section titled “Related Resources”