# API Data Sources

NQ integrates with several APIs to aggregate media data and user activity across multiple platforms. These APIs are divided into two categories: **User Data Integrations** and **Metadata Providers**.

## Overview

- **User Data Integrations:** Sync user activity, preferences, and consumption history
- **Metadata Providers:** Enrich media items with detailed information and relationships

---

## User Data Integrations (coming soon!)

### Spotify Web API

**Purpose**: Music streaming platform integration

**Data Collected**:
- User's saved albums
- Album metadata (title, artists, track count, release date)
- Cover artwork
- Record labels

**Authentication**: OAuth 2.0 Client Credentials Flow

---

**More coming in the future!**

---

## Metadata Providers

These APIs provide enriched metadata for media items discovered through user integrations or direct search.

### TMDB (The Movie Database)

**Purpose**: Comprehensive movie and TV show metadata

**Data Collected**:
- Movie/TV show details (title, description, release dates)
- Genres, budget, box office revenue, runtime
- Cast and crew credits with person IDs
- Production companies and countries
- Poster images and artwork
- Similar titles
- Person filmography

**Authentication**: API Read Access Token (Bearer token)

**Environment Variables**:
```bash
TMDB_API_READ_ACCESS_TOKEN=your_bearer_token
```

**How to Get Credentials**:
1. Create account at [TMDB](https://www.themoviedb.org/)
2. Visit [API Settings](https://www.themoviedb.org/settings/api)
3. Request an API key
4. Use the v4 API Read Access Token

**Implementation**: `nq/backend/metadata/video.go`

**Library Used**: `github.com/cyruzin/golang-tmdb` - Official Go client

---

### IGDB (Internet Game Database)

**Purpose**: Comprehensive game metadata database

**Data Collected**:
- Game details (title, summary, release dates)
- Genres, themes, keywords
- Game modes, player perspectives
- Franchises, platforms
- Cover artwork
- Developers, publishers

**Authentication**: OAuth 2.0 via Twitch (IGDB is owned by Twitch)

**Environment Variables**:
```bash
IGDB_CLIENT_ID=your_twitch_client_id
IGDB_CLIENT_SECRET=your_twitch_client_secret
```

**How to Get Credentials**:
1. Visit [Twitch Developers Console](https://dev.twitch.tv/console)
2. Register a new application
3. Copy Client ID and Client Secret
4. Use these for IGDB API access

**Implementation**: `nq/backend/metadata/games.go`

---

### Open Library API

**Purpose**: Free, open book metadata database

**Data Collected**:
- Book details (title, authors, publishers)
- ISBN lookups (ISBN-10 and ISBN-13)
- Publication dates, page counts
- Cover images
- Subjects (topics, places, people, times)
- Language information

**Authentication**: None required (public API)

**Environment Variables**: None needed

**Implementation**: `nq/backend/metadata/books.go`

**Features**:
- ISBN-13 preferred over ISBN-10
- Multi-language support with ISO 639 conversion
- Smart title normalization for better search results
- Subject categorization (places, people, times)

**API Endpoints**:
- Book lookup: `https://openlibrary.org/api/books`
- Search: `https://openlibrary.org/search.json`
- Cover images: `https://covers.openlibrary.org/b/id/{id}-{size}.jpg`

---

## Configuration Guide

### Environment Setup

1. Copy the environment template:
   ```bash
   cd backend
   cp .envtemplate .env
   ```

2. Fill in credentials for the APIs you want to use:
   ```bash
   # User Data Integrations
   SPOTIFY_CLIENT_ID=your_value
   SPOTIFY_CLIENT_SECRET=your_value
   APPLE_MUSIC_DEVELOPER_TOKEN=your_value
   YOUTUBE_API_KEY=your_value
   TWITCH_CLIENT_ID=your_value
   TWITCH_CLIENT_SECRET=your_value
   STEAM_API_KEY=your_value
   INSTAPAPER_USERNAME=your_value
   INSTAPAPER_PASSWORD=your_value
   
   # Metadata Providers
   TMDB_API_READ_ACCESS_TOKEN=your_value
   IGDB_CLIENT_ID=your_value
   IGDB_CLIENT_SECRET=your_value
   # Open Library requires no credentials
   ```

3. The system gracefully handles missing credentials - only configured APIs will be active

### Authentication Methods Summary

| API | Method | Credentials Needed |
|-----|--------|-------------------|
| TMDB | Bearer Token | Read Access Token |
| IGDB | OAuth 2.0 (Twitch) | Twitch Client ID + Secret |
| Open Library | None | No credentials required |

---

## Data Flow Architecture

### Integration Framework

**Location**: `nq/backend/integrations/integrations.go`

The integration framework provides:
- Common interface for all integrations
- Manager pattern for orchestrating multiple services
- Standardized sync results with error collection
- Media type categorization (game, music, video, book, article)

### Metadata Service

**Location**: `nq/backend/metadata/metadata.go`

The metadata service provides:
- Unified service for all metadata fetchers
- Automatic fetcher initialization based on available credentials
- Graceful degradation when API keys are missing
- Language-aware metadata retrieval