TCGdex Rust SDK

A fast, robust, and type-safe Rust SDK for the TCGdex API. Query Pokuémon Trading Card Game data with ease. 🦀

use tcgdex_sdk::{TCGdex, Language};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Fetch a card in one line
    let tcgdex = TCGdex::new(Language::EN);
    let card = tcgdex.card.get("swsh3-136").await?;

    println!("Found: {} ({}/{})",
             card.name,
             card.local_id,
             card.set.card_count.total);
    Ok(())
}

⚡️ Quick Install

Add to your Cargo.toml:

[dependencies]
tcgdex_sdk = "0.1.0"

Or use cargo add:

cargo add tcgdex_sdk

🚀 Features

• Type-Safe: Full type safety with Rust's strong type system
• Async/Await: Built for modern Rust applications
• Zero Config: Works out of the box
• Multi-Language: Support for English, French, German, Japanese, Chinese, and more
• Rich Data: Access cards, sets, series, rarities, and more
• Error Handling: Comprehensive error handling with thiserror
• Testable: Unit and integration tests included

🎯 Quick Examples

Find Cards by Various Criteria

use tcgdex_sdk::{TCGdex, Language, Query};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let tcgdex = TCGdex::new(Language::EN);

    // Get the cards made by the illustrator
    let illustrator = tcgdex.illustrator.get("5ban Graphics").await?;

    // Get the data about the Sword & Shield serie by ID
    let series = tcgdex.serie.get("swsh").await?;

    // Get all cards with 110 HP
    let hp_cards = tcgdex.hp.get("110").await?;

    // List all available rarities
    let all_series = tcgdex.serie.list(None).await?;

    // List all cards with the name being "Furret"
    let mut query = Query::new();
    query.equal("name", "Furret");
    let furret_cards = tcgdex.card.list(Some(&query)).await?;

    Ok(())
}

Working with Sets and Series

use tcgdex_sdk::{TCGdex, Language, Extension};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let tcgdex = TCGdex::new(Language::EN);

    // Get set details
    let darkness_ablaze = tcgdex.set.get("swsh3").await?;
    println!("Set: {} ({} cards)",
             darkness_ablaze.name,
             darkness_ablaze.card_count.total);

    // Get series info
    let swsh = tcgdex.serie.get("swsh").await?;
    println!("Series: {} ({} sets)",
             swsh.name,
             swsh.sets.len());

    // Download a set logo
    if let Some(url) = darkness_ablaze.get_logo_url(Extension::PNG) {
        println!("Logo URL: {}", url);
        // You can download the image with:
        // let logo_bytes = darkness_ablaze.get_logo(&tcgdex, Extension::PNG).await?;
    }

    Ok(())
}

Working with Card Images

use tcgdex_sdk::{TCGdex, Language, Quality, Extension};
use std::fs::File;
use std::io::Write;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let tcgdex = TCGdex::new(Language::EN);

    // Get a card
    let card = tcgdex.card.get("base1-4").await?; // Charizard

    // Get high resolution PNG image URL
    if let Some(image_url) = card.get_image_url(Quality::HIGH, Extension::PNG) {
        println!("Image URL: {}", image_url);

        // Download image
        if let Some(image_bytes) = card.get_image(&tcgdex, Quality::HIGH, Extension::PNG).await? {
            // Save to file
            let mut file = File::create("charizard.png")?;
            file.write_all(&image_bytes)?;
            println!("Image saved to charizard.png");
        }
    }

    Ok(())
}

🛠 Available Endpoints

Card Data

tcgdex.card         // Core card data
tcgdex.rarity       // Card rarities
tcgdex.hp           // HP values
tcgdex.illustrator  // Card illustrators

Game Mechanics

tcgdex.type_        // Pokémon types
tcgdex.energy_type  // Energy types
tcgdex.retreat      // Retreat costs
tcgdex.stage        // Evolution stages

Card Details

tcgdex.variant         // Card variants
tcgdex.suffix          // Card suffixes
tcgdex.regulation_mark // Regulation marks
tcgdex.dex_id          // Pokédex IDs

Collections

tcgdex.set           // Card sets
tcgdex.serie         // Card series

🌐 Language Support

use tcgdex_sdk::{TCGdex, Language};

// Using enum (type-safe)
let tcgdex = TCGdex::new(Language::EN); // English
let tcgdex = TCGdex::new(Language::FR); // French

// After creating the instance you can change the language
let mut tcgdex = TCGdex::default(); // Default is EN
tcgdex.set_language(Language::FR);

Full list of languages available in the Language enum

🔄 Query Building

The SDK provides a powerful query builder for filtering API results:

use tcgdex_sdk::{TCGdex, Query};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let tcgdex = TCGdex::default();

    // Build a complex query
    let mut query = Query::new();
    query.contains("name", "Pikachu")
         .equal("types", "Electric")
         .greater_than("hp", 50)
         .sort("name", "asc");

    // Use the query
    let cards = tcgdex.card.list(Some(&query)).await?;
    println!("Found {} matching cards", cards.len());

    Ok(())
}

🤝 Contributing

We love contributions! Here's how:

1. 🍴 Fork it
2. 🌿 Create your feature branch (git checkout -b feature/amazing)
3. 🔧 Make your changes
4. 🚀 Push to the branch (git push origin feature/amazing)
5. 🎉 Open a PR

📘 Documentation

• Full API Documentation
• Rust SDK Guide
• Rust Docs (docs.rs)

💬 Community & Support

• Discord Server - Get help and discuss features
• GitHub Issues - Bug reports and feature requests

📜 License

MIT © TCGdex