Skip to content

API Data Sources

Jump to bottom
Nathan Grilliot edited this page Feb 10, 2026 · 2 revisions

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:

TMDB_API_READ_ACCESS_TOKEN=your_bearer_token

How to Get Credentials:

  1. Create account at TMDB
  2. Visit API Settings
  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:

IGDB_CLIENT_ID=your_twitch_client_id
IGDB_CLIENT_SECRET=your_twitch_client_secret

How to Get Credentials:

  1. Visit Twitch Developers 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:

    cd backend
cp .envtemplate .env

  2. Fill in credentials for the APIs you want to use:

    # 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

Clone this wiki locally