streaming-buddy/references/tmdb-api.md

TMDB API Reference

Getting API Key

1. Create account: https://www.themoviedb.org/signup
2. Go to Settings → API
3. Request API key (choose "Developer" → personal use)
4. Copy API Key (v3 auth)

Endpoints Used

Search Multi (Movies + TV)

GET /search/multi?api_key={key}&query={query}&language=de-DE

Response:

{
  "results": [
    {
      "id": 106379,
      "media_type": "tv",
      "name": "Fallout",
      "first_air_date": "2024-04-10",
      "vote_average": 8.5,
      "overview": "...",
      "poster_path": "/path.jpg"
    }
  ]
}

TV Show Details

GET /tv/{id}?api_key={key}&language=de-DE&append_to_response=credits,watch/providers

Response includes:

• Basic info (name, overview, genres)
• Seasons and episodes count
• Cast and crew (credits)
• Streaming availability (watch/providers)

Movie Details

GET /movie/{id}?api_key={key}&language=de-DE&append_to_response=credits,watch/providers

Discover (for recommendations)

GET /discover/tv?api_key={key}&language=de-DE&with_genres={genre_ids}&watch_region=DE&with_watch_providers={provider_ids}&sort_by=vote_average.desc

Watch Providers

The watch/providers response includes availability by region:

{
  "watch/providers": {
    "results": {
      "DE": {
        "flatrate": [
          {"provider_id": 9, "provider_name": "Amazon Prime Video"}
        ],
        "rent": [...],
        "buy": [...]
      }
    }
  }
}

Genre IDs

Genre	TV ID	Movie ID
Action & Adventure	10759	28
Animation	16	16
Comedy	35	35
Crime	80	80
Documentary	99	99
Drama	18	18
Family	10751	10751
Fantasy	10765	14
Horror	-	27
Mystery	9648	9648
Romance	-	10749
Sci-Fi & Fantasy	10765	878
Thriller	-	53
War & Politics	10768	10752
Western	37	37

Rate Limits

• 40 requests per 10 seconds
• Cache responses for at least 1 hour (search) or 24 hours (details)

Image URLs

Base URL: https://image.tmdb.org/t/p/

Sizes:

• Poster: w92, w154, w185, w342, w500, w780, original
• Backdrop: w300, w780, w1280, original
• Profile: w45, w185, h632, original