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**:
```javascript
// 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**:
```javascript
// 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**:
```javascript
// 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**
```javascript
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**
```javascript
// 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**
```bash
# 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**
```bash
npm install node-fetch
```

### **2. Set Environment Variables**
```bash
# .env
REACT_APP_API_URL=http://localhost:8000
TCG_VAULT_TOKEN=your_auth_token_here
```

### **3. Run Database Population**
```bash
# 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**
```javascript
// 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!