TCGdex API

https://tcgdex.dev
Admin
TCGdex API is a multilingual, open-source API providing comprehensive Pokémon TCG card information...
Tokens:46,986
Snippets:368
Trust Score:6.8
Update:1 day ago
Show doc for...
Tokens:
Raw
### Install @tcgdex/sdk with Bun

Source: https://tcgdex.dev/sdks/javascript

Install the SDK using Bun in a terminal.

```bash
bun i @tcgdex/sdk
```

--------------------------------

### Install @tcgdex/sdk with Yarn

Source: https://tcgdex.dev/sdks/javascript

Install the SDK using Yarn in a terminal.

```bash
yarn add @tcgdex/sdk
```

--------------------------------

### Install @tcgdex/sdk with PNPM

Source: https://tcgdex.dev/sdks/javascript

Install the SDK using PNPM in a terminal.

```bash
pnpm add @tcgdex/sdk
```

--------------------------------

### Install @tcgdex/sdk with npm

Source: https://tcgdex.dev/sdks/javascript

Install the SDK using npm in a terminal.

```bash
npm i @tcgdex/sdk
```

--------------------------------

### Install SDK via Composer

Source: https://tcgdex.dev/sdks/php

Installs the TCGdex PHP SDK using Composer. This is the first step in setting up the SDK.

```bash
composer require tcgdex/sdk
```

--------------------------------

### Fetching Data

Source: https://tcgdex.dev/sdks/javascript

Examples of using the SDK to get specific cards, sets, series, and lists of all cards.

```APIDOC
## Fetching Data

### Description
Retrieve specific cards, sets, series, or lists of all cards using the SDK's dedicated endpoints.

### Methods
- `tcgdex.card.get(id)` - Get a specific card by ID.
- `tcgdex.set.get(id)` - Get a specific set by ID.
- `tcgdex.serie.get(id)` - Get a specific serie by ID.
- `tcgdex.card.list()` - Get a list of all cards.

### Parameters
- `id` (string) - Required - The identifier of the card, set, or serie (e.g., 'swsh3-136', 'swsh3', 'swsh').

### Request Example
```javascript
// 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();
```

### Response
Returns the requested data object or an array of objects for list operations.
```

--------------------------------

### Get and Download Card Images

Source: https://tcgdex.dev/sdks/python

Demonstrates how to retrieve image URLs and download images for cards using quality and extension parameters, either as strings or enums. The example uses a card fetched with sdk.card.get.

```python
from tcgdexsdk.enums import Quality, Extension

# Get a card
card = await sdk.card.get("swsh3-136")

# Get image URL with quality and format
image_url = card.get_image_url(quality="high", extension="png")
# Or using enums
image_url = card.get_image_url(Quality.HIGH, Extension.PNG)

# Download image directly
image_data = card.get_image(Quality.HIGH, Extension.PNG)
```

--------------------------------

### Basic Usage Example

Source: https://tcgdex.dev/sdks/typescript

Import the SDK, instantiate with language 'en', and fetch a card in an async context.

```typescript
// Import the SDK in ESM/TypeScript
import TCGdex from '@tcgdex/sdk'

// 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"
})();
```

--------------------------------

### Install SDK with pip

Source: https://tcgdex.dev/sdks/python

Installs the TCGdex Python SDK using pip. Run this command in your terminal.

```bash
pip install tcgdex-sdk
```

--------------------------------

### Query Examples

Source: https://tcgdex.dev/sdks/python

The SDK includes a powerful query builder to filter and sort results. The following examples demonstrate various query operations.

```APIDOC
## Query Examples

### Description
The SDK includes a powerful query builder to filter and sort results.

### Usage
```python
from tcgdexsdk import TCGdex, Query

sdk = TCGdex()

# Find all cards with specific name
furrets = await sdk.card.list(Query().equal("name", "Furret"))

# Find cards with 'ban' in illustrator name (case-insensitive)
ban_cards = await sdk.card.list(Query().contains("illustrator", "ban"))

# Find high HP Pokémon, sorted by HP
tanks = await sdk.card.list(
    Query()
        .greaterThan("hp", 200)
        .sort("hp", "desc")
)

# Find cards with no attacks but with abilities
basics = await sdk.card.list(
    Query()
        .isNull("attacks")
        .notNull("abilities")
)

# Pagination support
page2 = await sdk.card.list(
    Query().paginate(page=2, itemsPerPage=20)
)
```
```

--------------------------------

### Getting Random Data

Source: https://tcgdex.dev/sdks/javascript

Examples of retrieving random cards, sets, or series using the SDK.

```APIDOC
## Getting Random Data

### Description
Retrieve random cards, sets, or series using the SDK's random endpoints.

### Methods
- `tcgdex.random.card()` - Get a random card.
- `tcgdex.random.set()` - Get a random set.
- `tcgdex.random.serie()` - Get a random serie.

### Request Example
```javascript
// 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();
```

### Response
Returns a random data object of the requested type.
```

--------------------------------

### Filtering Example Request

Source: https://tcgdex.dev/rest/filtering-sorting-pagination

Example request to filter cards by name using the query parameter name=pikachu.

```http
https://api.tcgdex.net/v2/en/cards?name=pikachu
```

--------------------------------

### Using TCGdx SDK to list series and get set data

Source: https://tcgdex.dev/tcg-live

Initializes the TCGdx SDK with 'en' locale, lists all series, gets a specific series (sv), and retrieves complete set data including cards.

```javascript
const sdk = new TCGdx('en');

// Get all available series first to understand the card pool
const allSeries = await sdk.series.list();

// Get detailed information about a specific series
const series = await sdk.series.get('sv');
const { sets } = series;

// Get complete data for a specific set including all cards
const setData = await sdk.sets.get(sets[0].id);
const { cards } = setData;
```

--------------------------------

### Advanced Queries

Source: https://tcgdex.dev/sdks/javascript

Examples of using the Query system to filter, sort, and paginate card lists.

```APIDOC
## Advanced Queries

### Description
Use the Query class to build complex filters for card lists, including equality, range, containment, sorting, and pagination.

### Methods
- `tcgdex.card.list(query)` - Get a list of cards filtered by the provided query.

### Query Methods
- `Query.create()` - Creates a new query instance.
- `.equal(field, value)` - Matches exact value for a field.
- `.greaterOrEqualThan(field, value)` - Matches values greater than or equal to the given value.
- `.lesserThan(field, value)` - Matches values less than the given value.
- `.contains(field, value)` - Matches values containing the given substring.
- `.not.contains(field, value)` - Matches values not containing the given substring.
- `.sort(field, order)` - Sorts results by field in ascending ('ASC') or descending ('DESC') order.
- `.paginate(page, itemsPerPage)` - Paginates results with the given page number and items per page.

### Request Example
```javascript
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')
    .greaterOrEqualThan('hp', 60)
    .lesserThan('hp', 70)
    .sort('localId', 'ASC')
);

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

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

### Response
Returns an array of card objects matching the query criteria.
```

--------------------------------

### Sample Response: Sets List

Source: https://tcgdex.dev/rest/sets

Example JSON response from the sets endpoint, showing set objects with id, name, logo, symbol, and cardCount.

```json
[
  {
    "id": "base1",
    "name": "Base Set",
    "logo": "https://assets.tcgdex.net/en/base/base1/logo",
    "cardCount": {
      "total": 102,
      "official": 102
    }
  },
  // ...
  {
    "id": "swsh3",
    "name": "Darkness Ablaze",
    "logo": "https://assets.tcgdex.net/en/swsh/swsh3/logo",
    "symbol": "https://assets.tcgdex.net/univ/swsh/swsh3/symbol",
    "cardCount": {
      "total": 201,
      "official": 189
    }
  },
  // ...
  {
    "id": "sv06",
    "name": "Twilight Masquerade",
    "logo": "https://assets.tcgdex.net/en/sv/sv06/logo",
    "symbol": "https://assets.tcgdex.net/univ/sv/sv06/symbol",
    "cardCount": {
      "total": 226,
      "official": 167
    }
  }
]
```

--------------------------------

### Sample response for series request

Source: https://tcgdex.dev/rest/series

Example JSON response containing an array of SerieBrief objects with id, name, and logo fields.

```json
[
  {
    "id": "base",
    "name": "Base",
    "logo": "https://assets.tcgdex.net/en/base/base1/logo"
  },
  // ...
  {
    "id": "xy",
    "name": "XY",
    "logo": "https://assets.tcgdex.net/en/xy/xyp/logo"
  }
]
```

--------------------------------

### Pagination Request and Response

Source: https://tcgdex.dev/rest/filtering-sorting-pagination

Example request using pagination:page=3 and pagination:itemsPerPage=2, followed by the JSON response containing two set objects.

```http
https://api.tcgdex.net/v2/en/sets?pagination:page=3&pagination:itemsPerPage=2
```

```json
[
  {
    "id": "base3",
    "name": "Fossil",
    "logo": "https://assets.tcgdex.net/en/base/base3/logo",
    "symbol": "https://assets.tcgdex.net/univ/base/base3/symbol",
    "cardCount": {
      "total": 62,
      "official": 62
    }
  },
  {
    "id": "jumbo",
    "name": "Jumbo cards",
    "cardCount": {
      "total": 160,
      "official": 160
    }
  }
]
```

--------------------------------

### Sample 200 Response

Source: https://tcgdex.dev/rest/cards

Example response from the cards endpoint, returning an array of CardBrief objects with id, localId, name, and image fields.

```json
[
  {
    "id": "base4-1",
    "localId": "1",
    "name": "Alakazam",
    "image": "https://assets.tcgdex.net/en/base/base4/1"
  },
  // ...
  {
    "id": "xyp-XY99",
    "localId": "XY99",
    "name": "Aerodactyl Spirit Link",
    "image": "https://assets.tcgdex.net/en/xy/xyp/XY99"
  }
]
```

--------------------------------

### Kotlin Set helper methods

Source: https://tcgdex.dev/assets

Kotlin SDK helpers on a Set object to get symbol and logo URLs or directly fetch their image buffers.

```kotlin
  // get the final url
  val symbolURL = set.getSymbolUrl("webp")
  // get the symbol image buffer directly
  val symbol = set.getSymbol("webp")

  // get the final url
  val logoURL = set.getLogoUrl("webp")
  // get the logo image buffer directly
  val logo = set.getLogo("webp")
```

--------------------------------

### TypeScript SDK: Get Card

Source: https://tcgdex.dev/rest/card

Retrieves a card using the TCGdex TypeScript SDK. Requires prior SDK setup. The card ID is 'swsh3-136'.

```typescript
const card = await tcgdex.card.getCard('swsh3-136');
```

--------------------------------

### JavaScript SDK: Get Card

Source: https://tcgdex.dev/rest/card

Retrieves a card using the TCGdex JavaScript SDK. Requires prior SDK setup. The card ID is 'swsh3-136'.

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

--------------------------------

### Start Making Requests with Async and Sync Methods

Source: https://tcgdex.dev/sdks/python

Demonstrates the async and sync methods for fetching a card. The async method uses 'await', while the sync method uses 'getSync'.

```python
# Async usage
card = await tcgdex.card.get("swsh3-136")

# Sync usage
card = tcgdex.card.getSync("swsh3-136")
```

--------------------------------

### PHP SDK: Get Card

Source: https://tcgdex.dev/rest/card

Retrieves a card using the TCGdex PHP SDK. Requires prior SDK setup. The card ID is 'swsh3-136'.

```php
$card = $tcgdex->card->get('swsh3-136');
```

--------------------------------

### GET /en/cards - General Error Response

Source: https://tcgdex.dev/errors/general

Example of a general server error response returned when the server crashes during a request. The error should be reported to the support Discord channel or GitHub issues.

```APIDOC
## [GET] /en/cards

### Description
This endpoint returns a general server error when the server crashes during a request. The error response includes a type, title, status, endpoint, and method.

### Method
GET

### Endpoint
/en/cards

### Response
#### Error Response (500)
- **type** (string) - URL to the error documentation.
- **title** (string) - Error message indicating an unknown error occurred.
- **status** (integer) - HTTP status code (500).
- **endpoint** (string) - The endpoint that caused the error.
- **method** (string) - The HTTP method used.

#### Response Example
{
  "type": "https://tcgdex.dev/errors/general",
  "title": "An unknown error occured, please contact a developper with this message",
  "status": 500,
  "endpoint": "/en/cards",
  "method": "GET"
}
```

--------------------------------

### Basic Usage with Basic PHP

Source: https://tcgdex.dev/sdks/php

Initializes the SDK with language 'en', fetches a card by ID, and accesses card properties like name, illustrator, set name, types, and attacks.

```php
// Import the package
use TCGdex\TCGdex;

// Initialize the SDK with the language (defaults to "en" if not specified)
$tcgdex = new TCGdex("en");

// Fetch a card by ID
$card = $tcgdex->card->get('swsh3-136');

// Access card data
echo $card->name;           // "Furret"
echo $card->illustrator;    // "Mitsuhiro Arita"
echo $card->set->name;      // "Darkness Ablaze"

// Get card types, attacks, etc.
$types = $card->types;      // ["Colorless"]
$attacks = $card->attacks;  // Array of Attack objects
```

--------------------------------

### GET /jp/cards - Invalid Language Error

Source: https://tcgdex.dev/errors/language-invalid

Example of a 404 error response returned when an unsupported language code (e.g., 'jp') is used in an API request. The response includes the error type, title, status, endpoint, method, invalid language, and a list of valid languages.

```APIDOC
## GET /jp/cards

### Description
Returns a 404 error when the requested language code is not supported by the TCGdex API. The error indicates the invalid language and provides the list of valid language codes.

### Method
GET

### Endpoint
/jp/cards

### Parameters
#### Path Parameters
- **lang** (string) - Required - The language code used in the endpoint. In this example, 'jp' is invalid.

### Response
#### Error Response (404)
- **type** (string) - The error type URL.
- **title** (string) - A human-readable error title.
- **status** (integer) - The HTTP status code (404).
- **endpoint** (string) - The endpoint that caused the error.
- **method** (string) - The HTTP method used.
- **lang** (string) - The invalid language code used.
- **details** (string) - A detailed message listing valid language codes.

#### Response Example
{
  "type": "https://tcgdex.dev/errors/language-invalid",
  "title": "The chosen language is not available in the database",
  "status": 404,
  "endpoint": "/jp/cards",
  "method": "GET",
  "lang": "jp",
  "details": "You must use one of the following languages (en, fr, es, it, pt, pt-br, pt-pt, de, nl, pl, ru, ja, ko, zh-tw, id, th, zh-cn) while you used \"jp\""
}
```

--------------------------------

### Quick Example: Fetch a Card by ID

Source: https://tcgdex.dev/sdks/php

Initializes the TCGdex SDK with language 'en' and fetches a card by ID 'swsh3-136', then prints the card name, local ID, and total card count from the set.

```php
// Quick example
use TCGdex\TCGdex;

// Initialize the SDK
$tcgdex = new TCGdex("en");

// Fetch a card by ID
$card = $tcgdex->card->get('swsh3-136');

echo "Found: {$card->name} ({$card->localId}/{$card->set->cardCount->total})";
```

--------------------------------

### Configure custom HTTP and cache implementations

Source: https://tcgdex.dev/sdks/php

Demonstrates setting custom PSR-16 cache, PSR-17 HTTP factories, PSR-18 client, and cache TTL in milliseconds. The TTL example sets 1 hour.

```php
// Set custom implementations
use Psr\SimpleCache\CacheInterface;
use Psr\Http\Message\RequestFactoryInterface;
use Psr\Http\Message\ResponseFactoryInterface;
use Psr\Http\Client\ClientInterface;

// Set custom cache
TCGdex::$cache = /* PSR16 CacheInterface */;

// Set custom HTTP factories
TCGdex::$requestFactory = /* PSR17 RequestFactoryInterface */;
TCGdex::$responseFactory = /* PSR17 ResponseFactoryInterface */;

// Set custom HTTP client
TCGdex::$client = /* PSR18 ClientInterface */;

// Set cache TTL (in milliseconds)
TCGdex::$ttl = 3600 * 1000; // 1 hour
```

--------------------------------

### Initialize TCGdex and Access Endpoints

Source: https://tcgdex.dev/sdks/php

Shows how to instantiate the TCGdex client and access various endpoints for core data, card attributes, game mechanics, and card details.

```php
$tcgdex = new TCGdex();

// Main endpoints for core data
$tcgdex->card          // Card information
$tcgdex->set           // Card sets (e.g., "Darkness Ablaze")
$tcgdex->serie         // Card series (e.g., "Sword & Shield")

// Card attribute endpoints
$tcgdex->rarity        // Card rarities
$tcgdex->hp            // HP values
$tcgdex->illustrator   // Card illustrators
$tcgdex->category      // Card categories

// Game mechanics endpoints
$tcgdex->type          // Pokémon types
$tcgdex->energyType    // Energy types
$tcgdex->retreat       // Retreat costs
$tcgdex->stage         // Evolution stages

// Card details endpoints
$tcgdex->variant        // Card variants (holo, reverse, etc.)
$tcgdex->suffix         // Card suffixes
$tcgdex->regulationMark // Regulation marks
$tcgdex->dexId          // Pokédex IDs
$tcgdex->trainerType    // Trainer card types
```

--------------------------------

### Basic usage in Browser

Source: https://tcgdex.dev/sdks/javascript

Include the CDN script and use the SDK in a browser context.

```html
<script src="https://cdn.jsdelivr.net/npm/@tcgdex/sdk@2/dist/tcgdex.browser.global.min.js"></script>
<script>
  // Instantiate the SDK
  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"
  })();
</script>
```

--------------------------------

### Filtering Example Response

Source: https://tcgdex.dev/rest/filtering-sorting-pagination

Example JSON response showing filtered card results.

```json
[
  {
    "id": "basep-1",
    "localId": "1",
    "name": "Pikachu",
    "image": "https://assets.tcgdex.net/en/base/basep/1"
  },
  // ...
  {
    "id": "xyp-XY95",
    "localId": "XY95",
    "name": "Pikachu",
    "image": "https://assets.tcgdex.net/en/xy/xyp/XY95"
  }
]
```

--------------------------------

### Multi-language Support with TCGdx SDK

Source: https://tcgdex.dev/tcg-live

Demonstrates initializing SDKs for different languages, retrieving localized card data, fetching the same card in multiple languages, and searching using localized card names.

```javascript
// Initialize SDKs for different supported languages
const enSDK = new TCGdx('en');  // English
const jaSDK = new TCGdx('ja');  // Japanese
const frSDK = new TCGdx('fr');  // French
const deSDK = new TCGdx('de');  // German
const esSDK = new TCGdx('es');  // Spanish

// Retrieve card data in user's preferred language
const getLocalizedCard = async (cardId, language = 'en') => {
  const sdk = new TCGdx(language);
  return await sdk.cards.get(cardId);
};

// Get the same card in multiple languages for comparison
const getMultilingualCard = async (cardId) => {
  const languages = ['en', 'ja', 'fr', 'de'];
  const cardVersions = {};

  for (const lang of languages) {
    const sdk = new TCGdx(lang);
    cardVersions[lang] = await sdk.cards.get(cardId);
  }

  return cardVersions; // Returns card data with localized names/text
};

// Search using language-specific card names or terms
const searchInLanguage = async (searchTerm, language) => {
  const sdk = new TCGdx(language);
  return await sdk.cards.list({
    name: searchTerm // Search using localized card names
  });
};
```

--------------------------------

### Basic Usage with Symfony

Source: https://tcgdex.dev/sdks/php

Configures PSR-17 factories and a PSR-18 client for Symfony, then initializes the SDK and fetches a card by ID.

```php
use TCGdex\TCGdex;
use Symfony\Component\HttpClient\Psr18Client;
use Nyholm\Psr7\Factory\Psr17Factory;

// Create PSR-17 factories
$psr17Factory = new Psr17Factory();

// Set up the factories and client
TCGdex::$requestFactory = $psr17Factory;
TCGdex::$responseFactory = $psr17Factory;
TCGdex::$client = new Psr18Client();

// Initialize the SDK with the language
$tcgdex = new TCGdex("en");

// Fetch a card by ID
$card = $tcgdex->card->get('swsh3-136');
```

--------------------------------

### 404 Not Found Error Response Example

Source: https://tcgdex.dev/errors/not-found

Example JSON response body for a 404 Not Found error. The endpoint and method fields reflect the request that caused the error.

```json
{
  "type": "https://tcgdex.dev/errors/not-found",
  "title": "The resource you are trying to reach does not exists",
  "status": 404,
  "endpoint": "/v2/sfgdfh",
  "method": "GET"
}
```

--------------------------------

### Example RFC 9457 Error Response

Source: https://tcgdex.dev/errors

An example JSON error response following RFC 9457, showing the standard attributes: type, title, status, and additional fields like endpoint and method.

```json
{
  "type": "https://tcgdex.dev/errors/not-found",
  "title": "The resource you are trying to reach does not exists",
  "status": 404,
  "endpoint": "/v2/i-do-not-exists",
  "method": "GET"
}
```

--------------------------------

### Basic SDK Usage with Async and Sync Card Fetch

Source: https://tcgdex.dev/sdks/python

Initializes the TCGdex SDK and fetches a card using both async and sync methods. The async method uses 'await', while the sync method uses 'getSync'. Prints the card name and local ID.

```python
from tcgdexsdk import TCGdex, Extension

# Init the SDK
tcgdex = TCGdex()

# Fetch a card in one line
card = await tcgdex.card.get("swsh3-136")
# Or use the sync version
card = tcgdex.card.getSync("swsh3-136")

print(f"Found: {card.name} ({card.localId}/{card.set.cardCount.total})")
```

--------------------------------

### GET /v2/{locale}/suffixes

Source: https://tcgdex.dev/rest/other-fields

Lists all suffixes available in the specified locale.

```APIDOC
## GET /v2/{locale}/suffixes

### Description
Lists all suffixes available in the specified locale.

### Method
GET

### Endpoint
https://api.tcgdex.net/v2/{locale}/suffixes

### Parameters
#### Path Parameters
- **locale** (string) - Required - The locale code (e.g., 'en').

### Response
#### Success Response (200)
- **array of strings** - List of suffixes.

#### Response Example
["EX", "GX", "V"]
```

--------------------------------

### Advanced queries with Query.create()

Source: https://tcgdex.dev/sdks/javascript

Use the Query class to filter cards by exact name, HP range, ID contains/not contains, and pagination. The example initializes the SDK with 'en' locale and demonstrates chaining query methods.

```javascript
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)
);
```

--------------------------------

### Basic usage in Node/Bun

Source: https://tcgdex.dev/sdks/javascript

Import the SDK, instantiate with language 'en', and retrieve a card by ID.

```javascript
// 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"
})();
```

--------------------------------

### GET /v2/{locale}/variants

Source: https://tcgdex.dev/rest/other-fields

Lists all card variants available in the specified locale.

```APIDOC
## GET /v2/{locale}/variants

### Description
Lists all card variants available in the specified locale.

### Method
GET

### Endpoint
https://api.tcgdex.net/v2/{locale}/variants

### Parameters
#### Path Parameters
- **locale** (string) - Required - The locale code (e.g., 'en').

### Response
#### Success Response (200)
- **array of strings** - List of variants.

#### Response Example
["Normal", "Holo", "Reverse Holo"]
```

--------------------------------

### GET /v2/{locale}/trainertypes

Source: https://tcgdex.dev/rest/other-fields

Lists all trainer types available in the specified locale.

```APIDOC
## GET /v2/{locale}/trainertypes

### Description
Lists all trainer types available in the specified locale.

### Method
GET

### Endpoint
https://api.tcgdex.net/v2/{locale}/trainertypes

### Parameters
#### Path Parameters
- **locale** (string) - Required - The locale code (e.g., 'en').

### Response
#### Success Response (200)
- **array of strings** - List of trainer types.

#### Response Example
["Item", "Supporter", "Stadium"]
```

--------------------------------

### Query Builder - Create and Use

Source: https://tcgdex.dev/sdks/php

Shows how to create a Query instance, apply filters, sorting, and pagination, and use it to list filtered cards.

```APIDOC
## Query Builder - Create and Use

### Description
Create a new query with filters, sorting, and pagination, then use it to get filtered results from the card list.

### Usage
```php
use TCGdex\Query;

// Create a new query
$query = Query::create()
    ->equal('type', 'Colorless')  // Filter by exact match
    ->contains('name', 'Pikachu') // Filter by partial match
    ->sort('hp', 'desc')          // Sort by HP descending
    ->paginate(1, 20);            // Get page 1 with 20 items per page

// Use the query to get filtered results
$filteredCards = $tcgdex->card->list($query);
```

### Methods
- `equal(field, value)` - Filter by exact match
- `contains(field, value)` - Filter by partial match
- `sort(field, 'asc'|'desc')` - Sort results
- `paginate(page, itemsPerPage)` - Paginate results
```

--------------------------------

### GET /v2/{locale}/stages

Source: https://tcgdex.dev/rest/other-fields

Lists all Pokémon stages available in the specified locale.

```APIDOC
## GET /v2/{locale}/stages

### Description
Lists all Pokémon stages available in the specified locale.

### Method
GET

### Endpoint
https://api.tcgdex.net/v2/{locale}/stages

### Parameters
#### Path Parameters
- **locale** (string) - Required - The locale code (e.g., 'en').

### Response
#### Success Response (200)
- **array of strings** - List of stages.

#### Response Example
["Basic", "Stage 1", "Stage 2"]
```

--------------------------------

### Sample Response: Set data for swsh3

Source: https://tcgdex.dev/rest/set

Example JSON response for the set 'swsh3' (Darkness Ablaze), showing card counts, card list, legality, and metadata.

```json
{
  "cardCount": {
    "firstEd": 0,
    "holo": 64,
    "normal": 137,
    "official": 189,
    "reverse": 155,
    "total": 201
  },
  "cards": [
    {
      "id": "swsh3-1",
      "image": "https://assets.tcgdex.net/en/swsh/swsh3/1",
      "localId": "1",
      "name": "Butterfree V"
    },
    // ...
    {
      "id": "swsh3-136",
      "image": "https://assets.tcgdex.net/en/swsh/swsh3/136",
      "localId": "136",
      "name": "Furret"
    },
    // ...
    {
      "id": "swsh3-201",
      "image": "https://assets.tcgdex.net/en/swsh/swsh3/201",
      "localId": "201",
      "name": "Capture Energy"
    }
  ],
  "id": "swsh3",
  "legal": {
    "expanded": true,
    "standard": false
  },
  "logo": "https://assets.tcgdex.net/en/swsh/swsh3/logo",
  "name": "Darkness Ablaze",
  "releaseDate": "2020-08-14",
  "serie": {
    "id": "swsh",
    "name": "Sword & Shield"
  },
  "symbol": "https://assets.tcgdex.net/univ/swsh/swsh3/symbol"
}
```

--------------------------------

### GET /v2/{locale}/regulationmarks

Source: https://tcgdex.dev/rest/other-fields

Lists all regulation marks available in the specified locale.

```APIDOC
## GET /v2/{locale}/regulationmarks

### Description
Lists all regulation marks available in the specified locale.

### Method
GET

### Endpoint
https://api.tcgdex.net/v2/{locale}/regulationmarks

### Parameters
#### Path Parameters
- **locale** (string) - Required - The locale code (e.g., 'en').

### Response
#### Success Response (200)
- **array of strings** - List of regulation marks.

#### Response Example
["D", "E", "F"]
```

--------------------------------

### Configure TCGdex SDK Instance

Source: https://tcgdex.dev/sdks/javascript

Shows how to create a TCGdex instance with a specific language, change the language after initialization, set a custom API endpoint, and configure cache duration.

```javascript
// 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
```

--------------------------------

### GET /v2/{locale}/energytypes

Source: https://tcgdex.dev/rest/other-fields

Lists all energy types available in the specified locale.

```APIDOC
## GET /v2/{locale}/energytypes

### Description
Lists all energy types available in the specified locale.

### Method
GET

### Endpoint
https://api.tcgdex.net/v2/{locale}/energytypes

### Parameters
#### Path Parameters
- **locale** (string) - Required - The locale code (e.g., 'en').

### Response
#### Success Response (200)
- **array of strings** - List of energy types.

#### Response Example
["Grass", "Fire", "Water"]
```

--------------------------------

### Model Navigation - Card to Set

Source: https://tcgdex.dev/sdks/php

Shows how to navigate from a card to its set and from a set resume to a full set.

```APIDOC
## Model Navigation - Card to Set

### Description
Get a card and navigate to its set, then retrieve the full set from the set resume.

### Usage
```php
// Get a card and navigate to its set
$card = $tcgdex->card->get('swsh3-136');
$setResume = $card->set;              // Get SetResume from card
$fullSet = $setResume->toSet();       // Get full Set from SetResume
```
```

--------------------------------

### GET /v2/{locale}/dexids

Source: https://tcgdex.dev/rest/other-fields

Lists all Pokédex IDs available in the specified locale.

```APIDOC
## GET /v2/{locale}/dexids

### Description
Lists all Pokédex IDs available in the specified locale.

### Method
GET

### Endpoint
https://api.tcgdex.net/v2/{locale}/dexids

### Parameters
#### Path Parameters
- **locale** (string) - Required - The locale code (e.g., 'en').

### Response
#### Success Response (200)
- **array of integers** - List of Pokédex IDs.

#### Response Example
[1, 2, 3, 4]
```

--------------------------------

### Pagination and Batch Processing with TCGdx SDK

Source: https://tcgdex.dev/tcg-live

Shows how to paginate through all cards using the TCGdx SDK with a limit of 250 per page, and how to process multiple card IDs in batches of 50 using Promise.all for performance.

```javascript
const sdk = new TCGdx('en');

// Use pagination to handle large result sets efficiently
const getAllCards = async () => {
  const allCards = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await sdk.cards.list({
      page: page,
      limit: 250 // API maximum per page
    });

    allCards.push(...response.data);
    hasMore = response.data.length === 250;
    page++;
  }

  return allCards;
};

// Process multiple card requests efficiently using batch operations
const processBatch = async (cardIds) => {
  const batchSize = 50; // Optimal batch size for API performance
  const results = [];

  for (let i = 0; i < cardIds.length; i += batchSize) {
    const batch = cardIds.slice(i, i + batchSize);
    const batchPromises = batch.map(id => sdk.cards.get(id));
    const batchResults = await Promise.all(batchPromises);
    results.push(...batchResults);
  }

  return results;
};
```

--------------------------------

### GET /v2/{locale}/categories

Source: https://tcgdex.dev/rest/other-fields

Lists all card categories available in the specified locale.

```APIDOC
## GET /v2/{locale}/categories

### Description
Lists all card categories available in the specified locale.

### Method
GET

### Endpoint
https://api.tcgdex.net/v2/{locale}/categories

### Parameters
#### Path Parameters
- **locale** (string) - Required - The locale code (e.g., 'en').

### Response
#### Success Response (200)
- **array of strings** - List of categories.

#### Response Example
["Pokémon", "Trainer", "Energy"]
```

--------------------------------

### Navigate from Card to Set and Series

Source: https://tcgdex.dev/sdks/php

Demonstrates model navigation: retrieving a card, accessing its set resume via $card->set, converting it to a full set with toSet(), and iterating over a series' sets to access full set data including cards.

```php
// Get a card and navigate to its set
$card = $tcgdex->card->get('swsh3-136');
$setResume = $card->set;              // Get SetResume from card
$fullSet = $setResume->toSet();       // Get full Set from SetResume

// Get a series and navigate to its sets
$serie = $tcgdex->serie->get('swsh');
foreach ($serie->sets as $setResume) {
    $fullSet = $setResume->toSet();
    // Now you have access to all set data including cards
    $cards = $fullSet->cards;
}
```

--------------------------------

### GET /v2/{locale}/illustrators

Source: https://tcgdex.dev/rest/other-fields

Lists all card illustrators available in the specified locale.

```APIDOC
## GET /v2/{locale}/illustrators

### Description
Lists all card illustrators available in the specified locale.

### Method
GET

### Endpoint
https://api.tcgdex.net/v2/{locale}/illustrators

### Parameters
#### Path Parameters
- **locale** (string) - Required - The locale code (e.g., 'en').

### Response
#### Success Response (200)
- **array of strings** - List of illustrator names.

#### Response Example
["Ken Sugimori", "Mitsuhiro Arita"]
```

--------------------------------

### Get Set Logo and Symbol Images

Source: https://tcgdex.dev/sdks/python

Shows how to fetch a set and retrieve its logo and symbol URLs or download them directly, using the Extension enum for format.

```python
# Sets and series also have image methods
set_data = await sdk.set.get("swsh3")

logo_url = set_data.get_logo_url(Extension.PNG)
logo = set_data.get_logo(Extension.PNG)

symbol_url = set_data.get_symbol_url(Extension.WEBP)
symbol = set_data.get_symbol(Extension.WEBP)
```

--------------------------------

### Install PSR Implementations for Basic PHP

Source: https://tcgdex.dev/sdks/php

Adds required PSR-16, PSR-17, and PSR-18 implementations for basic PHP environments using Symfony Cache, Nyholm PSR-7, and Buzz HTTP client.

```bash
composer require symfony/cache nyholm/psr7 kriswallsmith/buzz
```

--------------------------------

### GET /v2/{locale}/rarities

Source: https://tcgdex.dev/rest/other-fields

Lists all card rarities available in the specified locale.

```APIDOC
## GET /v2/{locale}/rarities

### Description
Lists all card rarities available in the specified locale.

### Method
GET

### Endpoint
https://api.tcgdex.net/v2/{locale}/rarities

### Parameters
#### Path Parameters
- **locale** (string) - Required - The locale code (e.g., 'en').

### Response
#### Success Response (200)
- **array of strings** - List of rarities.

#### Response Example
["Common", "Uncommon", "Rare"]
```

--------------------------------

### GET /v2/{locale}/retreats

Source: https://tcgdex.dev/rest/other-fields

Lists all retreat costs available in the specified locale.

```APIDOC
## GET /v2/{locale}/retreats

### Description
Lists all retreat costs available in the specified locale.

### Method
GET

### Endpoint
https://api.tcgdex.net/v2/{locale}/retreats

### Parameters
#### Path Parameters
- **locale** (string) - Required - The locale code (e.g., 'en').

### Response
#### Success Response (200)
- **array of integers** - List of retreat costs.

#### Response Example
[0, 1, 2, 3]
```

--------------------------------

### PHP SDK: fetchCard('136', 'swsh3')

Source: https://tcgdex.dev/rest/set-card

Fetches a card by local ID and set ID using the PHP SDK. Requires prior SDK setup.

```PHP
$set = $tcgdex->fetchCard('136', 'swsh3');
```

--------------------------------

### GET /v2/{locale}/types

Source: https://tcgdex.dev/rest/other-fields

Lists all card types available in the specified locale.

```APIDOC
## GET /v2/{locale}/types

### Description
Lists all card types available in the specified locale.

### Method
GET

### Endpoint
https://api.tcgdex.net/v2/{locale}/types

### Parameters
#### Path Parameters
- **locale** (string) - Required - The locale code (e.g., 'en').

### Response
#### Success Response (200)
- **array of strings** - List of card types.

#### Response Example
["Pokémon", "Trainer", "Energy"]
```
Tokens:
Raw