> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streamforge.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Game Data & Content

> Working with game metadata, IGDB integration, and game-related content

The Streamforge External API provides access to game metadata from IGDB (Internet Game Database) and allows you to find content related to specific games.

## Game Endpoints

The API offers several endpoints for working with games:

* `GET /platforms/{platform}/games/{game_id}` - Get game by platform ID
* `POST /platforms/{platform}/games/bulk` - Get multiple games
* `GET /platforms/{platform}/games/{game_id}/content` - Get content for a game
* `GET /games/search` - Search games by name

## Platform Support

Games are available on different platforms:

* **Twitch**: Games are identified by Twitch game IDs
* **YouTube**: Games are identified by YouTube game channel IDs
* **IGDB**: Direct access using IGDB game IDs

## Finding Games

### Search by Name

The easiest way to find games is using the search endpoint:

```javascript theme={null}
const games = await fetch(
  '/games/search?q=minecraft&limit=20',
  {
    headers: { 'x-api-key': 'YOUR_API_KEY' }
  }
).then(r => r.json());

games.payload.forEach(game => {
  console.log(`${game.name} (IGDB: ${game.id})`);
});
```

### Filter by Platform

Search for games available on a specific platform:

```javascript theme={null}
// Only return games available on Twitch
const twitchGames = await fetch(
  '/games/search?q=minecraft&platform=twitch&limit=20',
  {
    headers: { 'x-api-key': 'YOUR_API_KEY' }
  }
).then(r => r.json());
```

## Game Data Structure

Games include IGDB metadata:

```json theme={null}
{
  "payload": {
    "id": "189165",
    "name": "Kill The Monster Z",
    "slug": "kill-the-monster-z",
    "first_release_date": "2017-03-01T00:00:00.000Z",
    "twitch_id": "2011938005",
    "youtube_id": "UCf_7CrLpgmot2vPKYwx5zQg"
  },
  "meta": {
    "source": "igdb",
    "received_at": "2025-01-27T12:00:00.000Z"
  }
}
```

**Key fields**:

* `id`: IGDB game ID (cross-platform identifier)
* `twitch_id`: Twitch game ID (if available on Twitch)
* `youtube_id`: YouTube game channel ID (if available on YouTube)
* `first_release_date`: When the game was first released

## Getting Games by Platform ID

### Twitch Game ID

```javascript theme={null}
const game = await fetch(
  '/platforms/twitch/games/2011938005',
  {
    headers: { 'x-api-key': 'YOUR_API_KEY' }
  }
).then(r => r.json());

console.log(game.payload.name); // Game name
console.log(game.payload.id); // IGDB ID
```

### YouTube Game Channel ID

```javascript theme={null}
const game = await fetch(
  '/platforms/youtube/games/UCf_7CrLpgmot2vPKYwx5zQg',
  {
    headers: { 'x-api-key': 'YOUR_API_KEY' }
  }
).then(r => r.json());
```

### IGDB Game ID

```javascript theme={null}
const game = await fetch(
  '/platforms/igdb/games/189165',
  {
    headers: { 'x-api-key': 'YOUR_API_KEY' }
  }
).then(r => r.json());
```

## Bulk Game Lookup

Fetch multiple games in a single request:

```javascript theme={null}
const games = await fetch(
  '/platforms/twitch/games/bulk',
  {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      game_ids: ["2011938005", "491487", "490377"]
    })
  }
).then(r => r.json());

games.payload.forEach(game => {
  console.log(`${game.name}: ${game.id}`);
});
```

## Getting Content for Games

Find streams and videos related to a specific game:

```javascript theme={null}
const content = await fetch(
  '/platforms/twitch/games/2011938005/content?limit=20&sort=views&order=desc',
  {
    headers: { 'x-api-key': 'YOUR_API_KEY' }
  }
).then(r => r.json());

content.payload.forEach(item => {
  console.log(`${item.title}: ${item.statistics.viewers.max} peak viewers`);
});
```

### Content Filtering

Filter game content by various criteria:

```javascript theme={null}
// Filter by content type
const streams = await fetch(
  '/platforms/twitch/games/2011938005/content?content_type=stream&limit=20',
  {
    headers: { 'x-api-key': 'YOUR_API_KEY' }
  }
).then(r => r.json());

// Filter by date range
const recentContent = await fetch(
  '/platforms/twitch/games/2011938005/content?start_date=2024-01-01&end_date=2024-12-31',
  {
    headers: { 'x-api-key': 'YOUR_API_KEY' }
  }
).then(r => r.json());
```

### Sorting Options

Sort game content by different statistics:

* `created_at` - When content was created (default)
* `views` - Total views
* `viewers` - Peak concurrent viewers

```javascript theme={null}
// Sort by views (descending)
const topContent = await fetch(
  '/platforms/twitch/games/2011938005/content?sort=views&order=desc&limit=10',
  {
    headers: { 'x-api-key': 'YOUR_API_KEY' }
  }
).then(r => r.json());
```

## IGDB Integration

Games are enriched with IGDB metadata. You can use IGDB IDs to:

1. **Fetch full game details** from IGDB API (cover art, ratings, genres, etc.)
2. **Cross-reference** games across platforms
3. **Get comprehensive metadata** not available in the Streamforge API

### Example: Using IGDB ID

```javascript theme={null}
// Get game from Streamforge API
const game = await fetch('/platforms/twitch/games/2011938005', {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
}).then(r => r.json());

const igdbId = game.payload.id; // "189165"

// Use IGDB ID to fetch full details from IGDB API
// (requires IGDB API credentials)
```

## Use Cases

### Trending Games Analysis

```javascript theme={null}
async function findTrendingGames(platform) {
  // 1. Search for popular games
  // 2. Get content for each game
  // 3. Analyze view counts and engagement
  // 4. Rank by popularity
}
```

### Game Content Discovery

```javascript theme={null}
async function discoverGameContent(gameName, platform) {
  // 1. Search for game
  const search = await fetch(`/games/search?q=${gameName}&platform=${platform}`);
  const games = await search.json();

  if (games.payload.length === 0) return [];

  // 2. Get content for the game
  const gameId = games.payload[0].twitch_id || games.payload[0].youtube_id;
  const content = await fetch(
    `/platforms/${platform}/games/${gameId}/content?limit=50&sort=views&order=desc`
  );

  return content.json();
}
```

### Cross-Platform Game Analysis

```javascript theme={null}
async function analyzeGameAcrossPlatforms(gameName) {
  // 1. Search for game
  const search = await fetch(`/games/search?q=${gameName}`);
  const games = await search.json();

  if (games.payload.length === 0) return null;

  const game = games.payload[0];

  // 2. Get content from both platforms
  const results = {};

  if (game.twitch_id) {
    const twitchContent = await fetch(
      `/platforms/twitch/games/${game.twitch_id}/content?limit=10`
    );
    results.twitch = await twitchContent.json();
  }

  if (game.youtube_id) {
    const youtubeContent = await fetch(
      `/platforms/youtube/games/${game.youtube_id}/content?limit=10`
    );
    results.youtube = await youtubeContent.json();
  }

  return results;
}
```

## Best Practices

<Tip>
  Use game search to find games by name, then use the returned IDs for subsequent requests. This is more reliable than guessing platform-specific IDs.
</Tip>

* **Search first**: Use `/games/search` to find games by name
* **Store IGDB IDs**: IGDB IDs are cross-platform identifiers
* **Filter by platform**: Use platform filters when you only need games from one platform
* **Paginate content**: Use cursor pagination for large content lists
* **Cache game data**: Game metadata doesn't change frequently

## Limitations

* **Games only on Twitch/YouTube**: Game content endpoints only work for Twitch and YouTube
* **IGDB platform**: When using `platform=igdb`, you can't fetch content (games don't have content on IGDB)
* **Search limits**: Search returns up to 100 results per query

<Warning>
  Game content endpoints (`/games/{game_id}/content`) only work for Twitch and YouTube platforms, not IGDB.
</Warning>