deckhearth/CARD_DATA_SOURCES.md

Card Data Sources Guide

This guide explains how to build out your card database using external APIs and data sources.

🎯 Recommended Data Sources

1. Scryfall API (Magic: The Gathering)

Best for MTG cards

• URL: https://api.scryfall.com
• Free: No API key required
• Rate Limit: 10 requests/second
• Coverage: All MTG cards with images, prices, rulings

Example Usage:

// Search for a card
const response = await fetch('https://api.scryfall.com/cards/named?fuzzy=lightning+bolt');
const card = await response.json();

// Search multiple cards
const searchResponse = await fetch('https://api.scryfall.com/cards/search?q=game:paper+type:creature');
const cards = await searchResponse.json();

2. Pokémon TCG API

Best for Pokémon cards

• URL: https://api.pokemontcg.io/v2
• Free: No authentication required
• Rate Limit: Generous limits
• Coverage: All Pokémon cards with images

Example Usage:

// Search for a card
const response = await fetch('https://api.pokemontcg.io/v2/cards?q=name:pikachu');
const cards = await response.json();

3. Yu-Gi-Oh! API

Best for Yu-Gi-Oh! cards

• URL: https://db.ygoprodeck.com/api/v7
• Free: Open source API
• Coverage: All Yu-Gi-Oh! cards

Example Usage:

// Search for a card
const response = await fetch('https://db.ygoprodeck.com/api/v7/cardinfo.php?fname=Blue-Eyes%20White%20Dragon');
const cards = await response.json();

4. Disney Lorcana

For Lorcana cards

• Status: No official API available yet
• Alternative: Manual data entry or community data scraping
• Future: May have official API when game matures

🚀 Implementation Strategy

Phase 1: Core Integration

1. Set up rate limiting for each API
2. Create unified search interface that queries all sources
3. Implement caching to avoid repeated requests
4. Add error handling for API failures

Phase 2: Database Population

1. Fetch popular cards from each game
2. Store in local database with proper metadata
3. Update pricing regularly
4. Add image caching for better performance

Phase 3: Advanced Features

1. Real-time pricing from multiple sources
2. Set completion tracking
3. Market trend analysis
4. Deck building suggestions

📊 Data Mapping

Universal Fields

Field	Description	Source
name	Card name	All APIs
game	Game identifier	All APIs
set_name	Set/expansion name	All APIs
set_code	Set abbreviation	All APIs
card_number	Collector number	All APIs
rarity	Rarity level	All APIs
image_url	Card image URL	All APIs
current_price	Market price	MTG, Pokémon

Game-Specific Fields

Magic: The Gathering

• mana_cost: Mana symbols {W}{U}{B}{R}{G}{C}
• cmc: Converted mana cost
• card_type: Full type line
• colors: Color identity
• oracle_text: Rules text
• power/toughness: Creature stats

Pokémon

• mana_cost: Energy requirements
• cmc: Total energy cost
• card_type: Card type + stage
• colors: Energy types
• power: HP value
• oracle_text: Effect text

Yu-Gi-Oh!

• mana_cost: Level/rank
• cmc: Level value
• card_type: Card type
• colors: Attribute
• oracle_text: Effect text
• power/toughness: ATK/DEF

🛠️ Usage Examples

Search Cards from External APIs

import cardDataService from '../services/cardDataSources';

// Search across all games
const cards = await cardDataService.searchCards('dragon');

// Search specific game
const mtgCards = await cardDataService.searchCards('lightning', 'MTG');

Add Cards to Database

// Fetch card from external API
const card = await mtgService.getCardByName('Lightning Bolt');

// Add to local database
const result = await databaseAPI.addCard(card);

Populate Database with Popular Cards

# Run the population script
node scripts/populate-card-database.js

📈 Performance Considerations

Rate Limiting

• Scryfall: 10 requests/second
• Pokémon API: 5 requests/second
• Yu-Gi-Oh! API: No strict limits

Caching Strategy

• Search results: Cache for 5 minutes
• Card details: Cache for 1 hour
• Images: Cache indefinitely
• Pricing: Update every 24 hours

Error Handling

• API failures: Retry with exponential backoff
• Rate limits: Implement proper queuing
• Network issues: Graceful degradation

🔧 Setup Instructions

1. Install Dependencies

npm install node-fetch

2. Set Environment Variables

# .env
REACT_APP_API_URL=http://localhost:8000
TCG_VAULT_TOKEN=your_auth_token_here

3. Run Database Population

# Populate with popular cards
node scripts/populate-card-database.js

# Or use the web interface
# Navigate to Cards page → "Browse Database" button

4. Test the Integration

// Test external API search
const cards = await cardDataService.searchCards('pikachu', 'POKEMON');
console.log('Found cards:', cards.length);

// Test database addition
const card = await mtgService.getCardByName('Lightning Bolt');
if (card) {
  await databaseAPI.addCard(card);
  console.log('Card added to database');
}

🎯 Next Steps

Immediate Actions

1. Test the APIs with the provided services
2. Populate your database with popular cards
3. Integrate the browser component into your app
4. Set up regular updates for pricing data

Future Enhancements

1. Add more games (Lorcana, Flesh and Blood, etc.)
2. Implement price tracking with alerts
3. Add set completion tracking
4. Create deck building suggestions
5. Add market analysis tools

📚 Additional Resources

• Scryfall API Docs: https://scryfall.com/docs/api
• Pokémon TCG API: https://dev.pokemontcg.io/
• Yu-Gi-Oh! API: https://ygoprodeck.com/api-guide/
• TCGPlayer API: https://docs.tcgplayer.com/

🚨 Important Notes

1. Respect rate limits - Implement proper throttling
2. Cache responses - Avoid unnecessary API calls
3. Handle errors gracefully - APIs can be unreliable
4. Update pricing regularly - Card values change frequently
5. Verify card data - Cross-reference with official sources

This implementation provides a solid foundation for building a comprehensive card database that can grow with your application's needs!