# TMDB API Coverage in NexStream

`TmdbApi.kt` — Retrofit interface backed by `TmdbApiKeyProvider`.

## Endpoints

### Catalog / Discovery
| Endpoint | Method | Notes |
|----------|--------|-------|
| `GET /3/trending/{media_type}/week` | `getTrending()` | Movies + TV |
| `GET /3/trending/{media_type}/day` | `getTrendingDay()` | Daily trending |
| `GET /3/movie/popular` | `getPopularMovies()` | |
| `GET /3/movie/top_rated` | `getTopRatedMovies()` | |
| `GET /3/movie/now_playing` | `getNowPlayingMovies()` | Region filterable |
| `GET /3/movie/upcoming` | `getUpcomingMovies()` | Region filterable |
| `GET /3/tv/popular` | `getPopularTv()` | |
| `GET /3/tv/top_rated` | `getTopRatedTv()` | |
| `GET /3/tv/airing_today` | `getAiringTodayTv()` | |
| `GET /3/tv/on_the_air` | `getOnTheAirTv()` | |
| `GET /3/search/multi` | `searchMulti()` | Cross-type search fallback |
| `GET /3/discover/movie` | `discoverMovies()` | Genre, provider, date filters |
| `GET /3/discover/tv` | `discoverTv()` | Genre, date, vote filters |

### Metadata / Detail
| Endpoint | Method | Notes |
|----------|--------|-------|
| `GET /3/movie/{id}` | `getMovieDetail()` | Full movie metadata |
| `GET /3/tv/{id}` | `getTvDetail()` | Full TV metadata |
| `GET /3/movie/{id}/external_ids` | `getMovieExternalIds()` | IMDb/TVDB cross-ref |
| `GET /3/tv/{id}/external_ids` | `getTvExternalIds()` | IMDb/TVDB cross-ref |
| `GET /3/configuration` | `getConfiguration()` | Image base URLs & sizes |

### Videos / Trailers
| Endpoint | Method | Notes |
|----------|--------|-------|
| `GET /3/movie/{id}/videos` | `getMovieVideos()` | Trailers, teasers, clips |
| `GET /3/tv/{id}/videos` | `getTvVideos()` | Trailers, teasers, clips |

`TmdbVideo` model has `youtubeUrl` (computed) and `isBestTrailer` (official + YouTube + Trailer type).

### Similar / Recommendations
| Endpoint | Method | Notes |
|----------|--------|-------|
| `GET /3/movie/{id}/similar` | `getSimilarMovies()` | "More Like This" |
| `GET /3/tv/{id}/similar` | `getSimilarTv()` | "More Like This" |

## Response Models
- `TmdbPagedResponse` + `TmdbResultItem` — paginated lists (trending, popular, discover). Has `toMetaPreview()`.
- `TmdbSimilarResponse` + `TmdbSimilarResult` — similar titles. Has `toMetaPreview()`.
- `TmdbMovieDetail` / `TmdbTvDetail` + `TmdbGenre` — full detail with genres.
- `TmdbVideosResponse` + `TmdbVideo` — video results with YouTube URL resolution.
- `TmdbExternalIds` / `TmdbConfiguration` — cross-reference and image config.

## Fallback Chain
In `DetailsViewModel.loadDetails()`: Stremio addon meta → TMDB detail (if null). Trailer: Stremio `meta.trailerUrl` → TMDB videos endpoint. Related/"More Like This": always via TMDB similar endpoints.

## Key Provider
`TmdbApiKeyProvider` supplies the API key. All endpoints take `apiKey` as a query parameter (not header). Key is blank → catalog/trailer/related features silently degrade to empty results.