tmdb

package
v0.3.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 9, 2026 License: GPL-3.0 Imports: 28 Imported by: 0

Documentation

Overview

Package tmdb is a TMDB API v3 client with rate limiting, retries, request coalescing and an ETag/TTL response cache.

These helpers support offline acceptance tests across package boundaries. Runtime callers use the production APIs in the other files.

Index

Constants

View Source 
const (
	VideoTrailer         = "Trailer"
	VideoTeaser          = "Teaser"
	VideoClip            = "Clip"
	VideoFeaturette      = "Featurette"
	VideoBehindTheScenes = "Behind the Scenes"
	VideoBloopers        = "Bloopers"
)

Video types TMDB returns from /videos endpoints.

View Source 
const ChangesMaxWindow = 14 * 24 * time.Hour

ChangesMaxWindow is the longest start_date..end_date range /changes accepts ("Invalid date range: Should be a range no longer than 14 days", https://developer.themoviedb.org/reference/changes-movie-list).

View Source 
const DefaultBaseURL = "https://api.themoviedb.org/3"
View Source 
const DefaultExportBaseURL = "https://files.tmdb.org/p/exports"

DefaultExportBaseURL is where TMDB publishes the daily exports.

View Source 
const MinClusterRate = 5

MinClusterRate is the floor, in requests per second, of a node's TMDB rate when a cluster divides the per-key budget (SetRateShare).

Variables

View Source 
var BundledKey string

BundledKey is set at build time via -ldflags "-X github.com/braedonsaunders/ether/internal/tmdb.BundledKey=...". Never commit a real key here.

View Source 
var ErrExportUnavailable = errors.New("tmdb: daily export unavailable")

ErrExportUnavailable means no export of the kind could be downloaded and no recent enough copy is kept. Callers fall back to /discover.

View Source 
var ErrNoKey = errors.New("tmdb: no API key configured")

ErrNoKey is returned when no TMDB key is configured or bundled.

View Source 
var ErrUnavailable = errors.New("tmdb: temporarily unreachable")

ErrUnavailable is returned without contacting TMDB while the circuit breaker is open: recent requests failed at the transport or with exhausted 429/5xx retries.

Functions

func Background 

func Background(ctx context.Context) context.Context

Background marks ctx's requests as bulk work: the catalogue sync, the per-id fill, the names walk and the tail build. They share the client's one request budget with viewer-facing requests (a poster lookup, the detail fetch that promotes a title on open, the live search fallback) but always yield to them: a background request takes a token only while the bucket holds more than a reserve kept for viewer-facing requests, and it never queues a reservation ahead of them. Unmarked requests are viewer-facing.

func IsBackground 

func IsBackground(ctx context.Context) bool

IsBackground reports whether ctx carries Background.

func IsBearerKey 

func IsBearerKey(key string) bool

IsBearerKey reports whether key looks like a v4 read-access token (JWT) rather than a 32-char v3 api_key.

func ParseDate 

func ParseDate(s string) time.Time

ParseDate parses a TMDB YYYY-MM-DD date (zero on empty/invalid).

func ParseExport 

func ParseExport(r io.Reader, fn func(ExportRow) error) (rows, malformed int, err error)

ParseExport streams a gzip JSON Lines export, calling fn (if not nil) for each well-formed row with a positive id. Blank lines are skipped; lines that do not decode, or are longer than 64 KiB, are counted as malformed and skipped. A UTF-8 BOM and CRLF line ends are accepted. A truncated or corrupt gzip stream is an error (the gzip trailer's CRC and length are checked at the end). Memory is bounded by one line.

func ParseExportNamed 

func ParseExportNamed(r io.Reader, fn func(ExportRow, string) error) (rows, malformed int, err error)

ParseExportNamed is ParseExport that also passes each row's original title (movies) or original name (series).

func ResolveKey 

func ResolveKey(cfg config.Catalog) string

ResolveKey picks the owner override, else the bundled key.

Types

type AltTitle added in v0.3.0 

type AltTitle struct {
	Country string `json:"iso_3166_1"`
	Title   string `json:"title"`
	Type    string `json:"type"`
}

AltTitle is one alternative title.

type AltTitles added in v0.3.0 

type AltTitles struct {
	Titles  []AltTitle `json:"titles"`
	Results []AltTitle `json:"results"`
}

AltTitles is the alternative_titles appendix: other names a title goes by (romanized originals such as "Sousou no Frieren", regional and working titles). Movies list them under titles, TV under results.

type CastMember 

type CastMember struct {
	ID          int64  `json:"id"`
	Name        string `json:"name"`
	Character   string `json:"character"`
	Job         string `json:"job"`
	Department  string `json:"department"`
	Order       int    `json:"order"`
	ProfilePath string `json:"profile_path"`
	// aggregate credits
	Roles []struct {
		Character string `json:"character"`
	} `json:"roles"`
	Jobs []struct {
		Job string `json:"job"`
	} `json:"jobs"`
}

type ChangedID 

type ChangedID struct {
	ID    int64 `json:"id"`
	Adult bool  `json:"adult"`
}

ChangedID is one entry of a /changes page.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a TMDB API client. Safe for concurrent use.

func New 

func New(key string, log *slog.Logger, opts ...Option) *Client

New creates a client with an explicit key (v3 api_key or v4 bearer).

func NewFromConfig 

func NewFromConfig(cfg config.Catalog, log *slog.Logger, opts ...Option) *Client

NewFromConfig creates a client from catalogue config, falling back to BundledKey.

func (*Client) ArtworkVariants 

func (c *Client) ArtworkVariants(ctx context.Context, t *core.Title, language string) (*Images, error)

func (*Client) CachedArtworkVariants added in v0.3.0 

func (c *Client) CachedArtworkVariants(t *core.Title, language string) (*Images, bool)

CachedArtworkVariants returns only fresh cached data. It never contacts TMDB, waits for an in-flight fetch, or exposes stale data as authoritative. A miss can be filled separately using ArtworkVariants.

func (*Client) Changes 

func (c *Client) Changes(ctx context.Context, tv bool, start, end time.Time, page int) (*Paged[ChangedID], error)

Changes pages /movie/changes or /tv/changes (tv true): the ids TMDB edited between start and end (UTC days, inclusive), 100 a page.

func (*Client) Close 

func (c *Client) Close()

Close releases the client (the rate limiter has no goroutine; Close is kept for callers that own the client).

func (*Client) CollectionDetails 

func (c *Client) CollectionDetails(ctx context.Context, id int64) (*CollectionDetails, error)

CollectionDetails fetches a franchise collection.

func (*Client) Configuration 

func (c *Client) Configuration(ctx context.Context) (*Configuration, error)

Configuration fetches /configuration (cached for ImageURL too).

func (*Client) DiscoverMovies 

func (c *Client) DiscoverMovies(ctx context.Context, p DiscoverParams) (*Paged[Movie], error)

DiscoverMovies pages /discover/movie.

func (*Client) DiscoverTV 

func (c *Client) DiscoverTV(ctx context.Context, p DiscoverParams) (*Paged[TVShow], error)

DiscoverTV pages /discover/tv.

func (*Client) EpisodeDetails 

func (c *Client) EpisodeDetails(ctx context.Context, tvID int64, season, episode int) (*Episode, error)

EpisodeDetails fetches one episode.

func (*Client) EpisodeExternalIDs 

func (c *Client) EpisodeExternalIDs(ctx context.Context, tvID int64, season, episode int) (*ExternalIDs, error)

EpisodeExternalIDs fetches external ids for one episode.

func (*Client) EpisodeGroup 

func (c *Client) EpisodeGroup(ctx context.Context, id string) (*EpisodeGroup, error)

func (*Client) EpisodeGroups 

func (c *Client) EpisodeGroups(ctx context.Context, show int64) ([]EpisodeGroupSummary, error)

func (*Client) EpisodeVideos 

func (c *Client) EpisodeVideos(ctx context.Context, tvID int64, season, episode int, lang string) ([]Video, error)

EpisodeVideos fetches /tv/{id}/season/{n}/episode/{e}/videos.

func (*Client) FindByExternalID 

func (c *Client) FindByExternalID(ctx context.Context, source, id string) (*FindResult, error)

FindByExternalID looks up by imdb ("tt...") or tvdb id. source accepts "imdb", "imdb_id", "tvdb", "tvdb_id".

func (*Client) Genres 

func (c *Client) Genres(ctx context.Context, mediaType string) ([]Genre, error)

Genres returns the genre list for "movie" or "tv".

func (*Client) GetJSON 

func (c *Client) GetJSON(ctx context.Context, path string, q url.Values, out any) error

GetJSON performs a rate-limited, cached GET of any TMDB v3 path (for example "/search/keyword") and decodes the JSON body into out. It lets callers reach endpoints this package has no typed helper for.

func (*Client) HasKey 

func (c *Client) HasKey() bool

HasKey reports whether a key is available.

func (*Client) ImageURL 

func (c *Client) ImageURL(path, size string) string

ImageURL builds a full image URL. Implements core.ImageURLFunc when used as method value.

func (*Client) ImageURLFunc 

func (c *Client) ImageURLFunc() core.ImageURLFunc

ImageURLFunc returns c.ImageURL as a core.ImageURLFunc.

func (*Client) Language 

func (c *Client) Language() string

Language returns the configured TMDB language.

func (*Client) Localized 

func (c *Client) Localized(ctx context.Context, t *core.Title, language string) (*core.Title, error)

Localized changes presentation only: certification, adult flag and identity remain the canonical catalogue's responsibility, never translated API fields.

func (*Client) MovieDetails 

func (c *Client) MovieDetails(ctx context.Context, id int64) (*MovieDetails, error)

MovieDetails fetches full movie details.

func (*Client) MovieDetailsFresh added in v0.2.37 

func (c *Client) MovieDetailsFresh(ctx context.Context, id int64) (*MovieDetails, error)

MovieDetailsFresh and TVDetailsFresh bypass the response cache for callers that must verify current release dates. They never serve a stale response.

func (*Client) MovieList 

func (c *Client) MovieList(ctx context.Context, list string, page int) (*Paged[Movie], error)

MovieList fetches popular|top_rated|now_playing|upcoming.

func (*Client) MovieRecommendations 

func (c *Client) MovieRecommendations(ctx context.Context, id int64, page int) (*Paged[Movie], error)

func (*Client) MovieReleaseDates added in v0.3.0 

func (c *Client) MovieReleaseDates(ctx context.Context, id int64) (*ReleaseDates, error)

MovieReleaseDates fetches only a movie's release dates and certifications (the catalogue's rating re-selection; far lighter than MovieDetails).

func (*Client) MovieSimilar 

func (c *Client) MovieSimilar(ctx context.Context, id int64, page int) (*Paged[Movie], error)

Similar / recommendations helpers.

func (*Client) MovieSummary 

func (c *Client) MovieSummary(ctx context.Context, id int64) (*MovieDetails, error)

MovieSummary is /movie/{id} without append_to_response: the fields a /discover result has, plus runtime, status and the IMDb id, in about 1.5 KB instead of the 130 KB a full detail fetch can be.

func (*Client) MovieVideos 

func (c *Client) MovieVideos(ctx context.Context, id int64, lang string) ([]Video, error)

MovieVideos fetches /movie/{id}/videos. lang overrides the client language for the include_video_language fallback list.

func (*Client) PersonCombinedCredits added in v0.2.7 

func (c *Client) PersonCombinedCredits(ctx context.Context, id int64) (*PersonCombinedCredits, error)

PersonCombinedCredits fetches /person/{id}/combined_credits.

func (*Client) PersonDetails 

func (c *Client) PersonDetails(ctx context.Context, id int64) (*Person, error)

PersonDetails fetches /person/{id}.

func (*Client) RateLimit 

func (c *Client) RateLimit() (perSec float64, burst int)

RateLimit reports the current request rate (per second) and burst.

func (*Client) Region 

func (c *Client) Region() string

Region returns the configured region.

func (*Client) SearchMovies 

func (c *Client) SearchMovies(ctx context.Context, query string, page int) (*Paged[Movie], error)

SearchMovies / SearchTV / SearchMulti.

func (*Client) SearchMulti 

func (c *Client) SearchMulti(ctx context.Context, query string, page int) (*Paged[MultiResult], error)

func (*Client) SearchTV 

func (c *Client) SearchTV(ctx context.Context, query string, page int) (*Paged[TVShow], error)

func (*Client) SeasonDetails 

func (c *Client) SeasonDetails(ctx context.Context, tvID int64, season int) (*SeasonDetails, error)

SeasonDetails fetches one season with its episodes.

func (*Client) SeasonVideos 

func (c *Client) SeasonVideos(ctx context.Context, tvID int64, season int, lang string) ([]Video, error)

SeasonVideos fetches /tv/{id}/season/{n}/videos.

func (*Client) SetConfiguration 

func (c *Client) SetConfiguration(cfg *Configuration)

SetConfiguration seeds the image configuration (tests / prefetch).

func (*Client) SetRateShare 

func (c *Client) SetRateShare(nodes int)

SetRateShare divides the configured request rate and burst by nodes, the number of live cluster nodes sharing the API key, with a floor of MinClusterRate requests per second (and burst) so a node of a large cluster still makes progress; nodes ≤ 1 restores the configured rate. TMDB's limit is per key (or per IP), so N nodes at the full rate would together exceed it.

func (*Client) TVContentRatings added in v0.3.0 

func (c *Client) TVContentRatings(ctx context.Context, id int64) (*ContentRatings, error)

TVContentRatings fetches only a show's per-country content ratings.

func (*Client) TVDetails 

func (c *Client) TVDetails(ctx context.Context, id int64) (*TVDetails, error)

TVDetails fetches full TV details.

func (*Client) TVDetailsFresh added in v0.2.37 

func (c *Client) TVDetailsFresh(ctx context.Context, id int64) (*TVDetails, error)

func (*Client) TVList 

func (c *Client) TVList(ctx context.Context, list string, page int) (*Paged[TVShow], error)

TVList fetches popular|top_rated|airing_today|on_the_air.

func (*Client) TVRecommendations 

func (c *Client) TVRecommendations(ctx context.Context, id int64, page int) (*Paged[TVShow], error)

func (*Client) TVSimilar 

func (c *Client) TVSimilar(ctx context.Context, id int64, page int) (*Paged[TVShow], error)

func (*Client) TVSummary 

func (c *Client) TVSummary(ctx context.Context, id int64) (*TVDetails, error)

TVSummary is /tv/{id} without append_to_response.

func (*Client) TVVideos 

func (c *Client) TVVideos(ctx context.Context, id int64, lang string) ([]Video, error)

TVVideos fetches /tv/{id}/videos.

func (*Client) TrendingAll 

func (c *Client) TrendingAll(ctx context.Context, window string, page int) (*Paged[MultiResult], error)

func (*Client) TrendingMovies 

func (c *Client) TrendingMovies(ctx context.Context, window string, page int) (*Paged[Movie], error)

Trending fetches /trending/{movie|tv|all}/{day|week}. For "all" results are MultiResult.

func (*Client) TrendingTV 

func (c *Client) TrendingTV(ctx context.Context, window string, page int) (*Paged[TVShow], error)

func (*Client) UpdateConfig 

func (c *Client) UpdateConfig(cfg config.Catalog)

UpdateConfig changes credentials and locale without replacing the client held by catalogue workers. Existing requests finish with their original snapshot; they cannot populate the new configuration's cache.

func (*Client) UserList added in v0.3.3 

func (c *Client) UserList(ctx context.Context, id int64, page int) (UserListPage, error)

UserList retrieves one page using the configured TMDB credentials and cache.

type CollectionDetails 

type CollectionDetails struct {
	ID           int64   `json:"id"`
	Name         string  `json:"name"`
	Overview     string  `json:"overview"`
	PosterPath   string  `json:"poster_path"`
	BackdropPath string  `json:"backdrop_path"`
	Parts        []Movie `json:"parts"`
}

CollectionDetails is /collection/{id}.

type CollectionRef 

type CollectionRef struct {
	ID           int64  `json:"id"`
	Name         string `json:"name"`
	PosterPath   string `json:"poster_path"`
	BackdropPath string `json:"backdrop_path"`
}

type Company 

type Company struct {
	ID            int    `json:"id"`
	Name          string `json:"name"`
	LogoPath      string `json:"logo_path"`
	OriginCountry string `json:"origin_country"`
}

type Configuration 

type Configuration struct {
	Images struct {
		BaseURL       string   `json:"base_url"`
		SecureBaseURL string   `json:"secure_base_url"`
		BackdropSizes []string `json:"backdrop_sizes"`
		LogoSizes     []string `json:"logo_sizes"`
		PosterSizes   []string `json:"poster_sizes"`
		ProfileSizes  []string `json:"profile_sizes"`
		StillSizes    []string `json:"still_sizes"`
	} `json:"images"`
	ChangeKeys []string `json:"change_keys"`
}

type ContentRatings 

type ContentRatings struct {
	Results []struct {
		ISO3166 string `json:"iso_3166_1"`
		Rating  string `json:"rating"`
	} `json:"results"`
}

type Country 

type Country struct {
	ISO3166 string `json:"iso_3166_1"`
	Name    string `json:"name"`
}

type Credits 

type Credits struct {
	Cast []CastMember `json:"cast"`
	Crew []CastMember `json:"crew"`
}

type DiscoverParams 

type DiscoverParams struct {
	Page                 int
	SortBy               string // e.g. popularity.desc, vote_count.desc, primary_release_date.desc
	VoteCountGTE         int
	VoteAverageGTE       float64
	WithGenres           string // comma/pipe list of genre ids
	Year                 int    // primary_release_year (movie) / first_air_date_year (tv)
	ReleaseDateGTE       string // YYYY-MM-DD
	ReleaseDateLTE       string
	FirstAirGTE          string
	FirstAirLTE          string
	IncludeAdult         bool
	WithOriginalLanguage string
	Region               string
	Extra                url.Values // merged last
}

DiscoverParams controls discover queries. Zero values are omitted.

type Episode 

type Episode struct {
	ID            int64        `json:"id"`
	Name          string       `json:"name"`
	Overview      string       `json:"overview"`
	EpisodeNumber int          `json:"episode_number"`
	SeasonNumber  int          `json:"season_number"`
	AirDate       string       `json:"air_date"`
	Runtime       *int         `json:"runtime"`
	StillPath     string       `json:"still_path"`
	VoteAverage   float64      `json:"vote_average"`
	VoteCount     int          `json:"vote_count"`
	ShowID        int64        `json:"show_id"`
	Crew          []CastMember `json:"crew"`
	GuestStars    []CastMember `json:"guest_stars"`
}

Episode is a TV episode.

type EpisodeGroup 

type EpisodeGroup struct {
	EpisodeGroupSummary
	Groups []EpisodeSubgroup `json:"groups"`
}

type EpisodeGroupSummary 

type EpisodeGroupSummary struct {
	ID           string `json:"id"`
	Name         string `json:"name"`
	Description  string `json:"description"`
	Type         int    `json:"type"`
	EpisodeCount int    `json:"episode_count"`
	GroupCount   int    `json:"group_count"`
}

EpisodeGroupSummary describes a TMDB alternate order (type 1 original air, 2 absolute, 3 DVD, 4 digital, 5 story arc, 6 production, 7 TV).

type EpisodeSubgroup 

type EpisodeSubgroup struct {
	ID       string           `json:"id"`
	Name     string           `json:"name"`
	Order    int              `json:"order"`
	Episodes []OrderedEpisode `json:"episodes"`
}

type ExportInfo 

type ExportInfo struct {
	Kind ExportKind
	// Day is the export's publication day (UTC midnight).
	Day       time.Time
	Rows      int
	Malformed int
	// Cached is true when this call read the copy kept from an earlier
	// download: it is today's, or no newer day could be downloaded.
	Cached bool
}

ExportInfo describes the file one Each call read.

type ExportKind 

type ExportKind string

ExportKind names one daily export file. 

const (
	ExportMovies      ExportKind = "movie_ids"
	ExportTV          ExportKind = "tv_series_ids"
	ExportAdultMovies ExportKind = "adult_movie_ids"
	ExportAdultTV     ExportKind = "adult_tv_series_ids"
)

type ExportOption 

type ExportOption func(*Exports)

ExportOption customises Exports.

func WithExportBackoff 

func WithExportBackoff(d time.Duration) ExportOption

WithExportBackoff sets the first retry delay of a failed download.

func WithExportBaseURL 

func WithExportBaseURL(u string) ExportOption

WithExportBaseURL points Exports at another host (tests, mirrors).

func WithExportClock 

func WithExportClock(now func() time.Time) ExportOption

WithExportClock sets the clock that picks the export day.

func WithExportHTTPClient 

func WithExportHTTPClient(c *http.Client) ExportOption

WithExportHTTPClient replaces the download client.

type ExportRow 

type ExportRow struct {
	ID         int64   `json:"id"`
	Popularity float64 `json:"popularity"`
	Adult      bool    `json:"adult"`
	Video      bool    `json:"video"`
}

ExportRow is one line of an export. Titles and names are not decoded.

type Exports 

type Exports struct {
	// contains filtered or unexported fields
}

Exports downloads, verifies and keeps the latest good copy of each daily export in dir, and streams it. Safe for concurrent use.

func NewExports 

func NewExports(dir string, log *slog.Logger, opts ...ExportOption) *Exports

NewExports keeps downloaded exports in dir (created on first use).

func (*Exports) Each 

func (e *Exports) Each(ctx context.Context, kind ExportKind, fn func(ExportRow) error) (ExportInfo, error)

Each calls fn for every row of the newest available export of kind: the newest published day it can download, else the kept copy if it is at most two weeks old. The file is verified (complete gzip, at most 1% malformed lines) before any row is passed on. fn's error stops the stream.

func (*Exports) EachNamed 

func (e *Exports) EachNamed(ctx context.Context, kind ExportKind, fn func(ExportRow, string) error) (ExportInfo, error)

EachNamed is Each with each row's original title or name.

type ExternalIDs 

type ExternalIDs struct {
	ID          int64  `json:"id"`
	IMDBID      string `json:"imdb_id"`
	TVDBID      int64  `json:"tvdb_id"`
	FacebookID  string `json:"facebook_id"`
	InstagramID string `json:"instagram_id"`
	TwitterID   string `json:"twitter_id"`
	WikidataID  string `json:"wikidata_id"`
}

type FindResult 

type FindResult struct {
	MovieResults     []Movie         `json:"movie_results"`
	TVResults        []TVShow        `json:"tv_results"`
	TVEpisodeResults []Episode       `json:"tv_episode_results"`
	TVSeasonResults  []SeasonSummary `json:"tv_season_results"`
	PersonResults    []Person        `json:"person_results"`
}

FindResult is /find/{id}.

type Genre 

type Genre struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

type GenreList 

type GenreList struct {
	Genres []Genre `json:"genres"`
}

type HTTPError 

type HTTPError struct {
	StatusCode int
	StatusMsg  string
	Body       string
}

HTTPError is a non-2xx TMDB response.

func (*HTTPError) Error 

func (e *HTTPError) Error() string

func (*HTTPError) Is 

func (e *HTTPError) Is(target error) bool

type ImageFile 

type ImageFile struct {
	FilePath string  `json:"file_path"`
	Width    int     `json:"width"`
	Height   int     `json:"height"`
	ISO639   string  `json:"iso_639_1"`
	VoteAvg  float64 `json:"vote_average"`
}

type Images 

type Images struct {
	Backdrops []ImageFile `json:"backdrops"`
	Posters   []ImageFile `json:"posters"`
	Logos     []ImageFile `json:"logos"`
	Still     []ImageFile `json:"stills"`
}

type Keyword 

type Keyword struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

type Keywords 

type Keywords struct {
	Keywords []Keyword `json:"keywords"`
	Results  []Keyword `json:"results"` // tv uses results
}

type Language 

type Language struct {
	ISO639 string `json:"iso_639_1"`
	Name   string `json:"name"`
}

type Movie 

type Movie struct {
	ID               int64   `json:"id"`
	Title            string  `json:"title"`
	OriginalTitle    string  `json:"original_title"`
	Overview         string  `json:"overview"`
	PosterPath       string  `json:"poster_path"`
	BackdropPath     string  `json:"backdrop_path"`
	ReleaseDate      string  `json:"release_date"`
	GenreIDs         []int   `json:"genre_ids"`
	Genres           []Genre `json:"genres"`
	OriginalLanguage string  `json:"original_language"`
	Popularity       float64 `json:"popularity"`
	VoteAverage      float64 `json:"vote_average"`
	VoteCount        int     `json:"vote_count"`
	Adult            bool    `json:"adult"`
	// Video marks a video release (a recorded concert, a compilation)
	// rather than a feature. /discover leaves them out unless asked.
	Video     bool   `json:"video"`
	MediaType string `json:"media_type"`
}

Movie is a list/search/discover movie item.

type MovieDetails 

type MovieDetails struct {
	Movie
	Tagline           string         `json:"tagline"`
	Runtime           int            `json:"runtime"`
	Status            string         `json:"status"`
	IMDBID            string         `json:"imdb_id"`
	Budget            int64          `json:"budget"`
	Revenue           int64          `json:"revenue"`
	Homepage          string         `json:"homepage"`
	BelongsTo         *CollectionRef `json:"belongs_to_collection"`
	ProductionCompany []Company      `json:"production_companies"`
	ProductionCountry []Country      `json:"production_countries"`
	SpokenLanguages   []Language     `json:"spoken_languages"`
	Credits           *Credits       `json:"credits"`
	ReleaseDates      *ReleaseDates  `json:"release_dates"`
	ExternalIDs       *ExternalIDs   `json:"external_ids"`
	Images            *Images        `json:"images"`
	Keywords          *Keywords      `json:"keywords"`
	AlternativeTitles *AltTitles     `json:"alternative_titles"`
	Similar           *Paged[Movie]  `json:"similar"`
	Recommendations   *Paged[Movie]  `json:"recommendations"`
}

MovieDetails is /movie/{id} with append_to_response.

type MultiResult 

type MultiResult struct {
	ID               int64   `json:"id"`
	MediaType        string  `json:"media_type"`
	Title            string  `json:"title"`
	Name             string  `json:"name"`
	OriginalTitle    string  `json:"original_title"`
	OriginalName     string  `json:"original_name"`
	Overview         string  `json:"overview"`
	PosterPath       string  `json:"poster_path"`
	BackdropPath     string  `json:"backdrop_path"`
	ProfilePath      string  `json:"profile_path"`
	ReleaseDate      string  `json:"release_date"`
	FirstAirDate     string  `json:"first_air_date"`
	GenreIDs         []int   `json:"genre_ids"`
	OriginalLanguage string  `json:"original_language"`
	Popularity       float64 `json:"popularity"`
	VoteAverage      float64 `json:"vote_average"`
	VoteCount        int     `json:"vote_count"`
}

MultiResult is one /search/multi item (movie, tv or person fields unioned).

func (MultiResult) AsMovie 

func (m MultiResult) AsMovie() Movie

func (MultiResult) AsTV 

func (m MultiResult) AsTV() TVShow

type Network 

type Network struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

type Option 

type Option func(*options)

Option customises a Client.

func WithBaseURL 

func WithBaseURL(u string) Option

func WithCacheTTL 

func WithCacheTTL(d time.Duration) Option

func WithMaxRetries 

func WithMaxRetries(n int) Option

func WithRateLimit 

func WithRateLimit(perSec float64, burst int) Option

type OrderedEpisode 

type OrderedEpisode struct {
	Episode
	Order int `json:"order"`
}

type Paged 

type Paged[T any] struct {
	Page         int `json:"page"`
	Results      []T `json:"results"`
	TotalPages   int `json:"total_pages"`
	TotalResults int `json:"total_results"`
}

Paged is a TMDB paged list response.

type Person 

type Person struct {
	ID                 int64   `json:"id"`
	Name               string  `json:"name"`
	Biography          string  `json:"biography"`
	Birthday           string  `json:"birthday"`
	Deathday           string  `json:"deathday"`
	PlaceOfBirth       string  `json:"place_of_birth"`
	ProfilePath        string  `json:"profile_path"`
	KnownForDepartment string  `json:"known_for_department"`
	Popularity         float64 `json:"popularity"`
	IMDBID             string  `json:"imdb_id"`
}

type PersonCombinedCredits added in v0.2.7 

type PersonCombinedCredits struct {
	ID   int64          `json:"id"`
	Cast []PersonCredit `json:"cast"`
	Crew []PersonCredit `json:"crew"`
}

PersonCombinedCredits is /person/{id}/combined_credits.

type PersonCredit added in v0.2.7 

type PersonCredit struct {
	MultiResult
	Character    string `json:"character"`
	Job          string `json:"job"`
	Department   string `json:"department"`
	EpisodeCount int    `json:"episode_count"`
}

PersonCredit is one work in /person/{id}/combined_credits.

type ReleaseDateEntry 

type ReleaseDateEntry struct {
	Certification string `json:"certification"`
	ReleaseDate   string `json:"release_date"`
	Type          int    `json:"type"`
	Note          string `json:"note"`
}

type ReleaseDates 

type ReleaseDates struct {
	Results []struct {
		ISO3166     string             `json:"iso_3166_1"`
		ReleaseDate []ReleaseDateEntry `json:"release_dates"`
	} `json:"results"`
}

type SeasonDetails 

type SeasonDetails struct {
	ID           int64     `json:"id"`
	Name         string    `json:"name"`
	Overview     string    `json:"overview"`
	SeasonNumber int       `json:"season_number"`
	AirDate      string    `json:"air_date"`
	PosterPath   string    `json:"poster_path"`
	Episodes     []Episode `json:"episodes"`
	VoteAverage  float64   `json:"vote_average"`
}

SeasonDetails is /tv/{id}/season/{n}.

type SeasonSummary 

type SeasonSummary struct {
	ID           int64   `json:"id"`
	Name         string  `json:"name"`
	Overview     string  `json:"overview"`
	SeasonNumber int     `json:"season_number"`
	EpisodeCount int     `json:"episode_count"`
	AirDate      string  `json:"air_date"`
	PosterPath   string  `json:"poster_path"`
	VoteAverage  float64 `json:"vote_average"`
}

type TVDetails 

type TVDetails struct {
	TVShow
	Tagline           string          `json:"tagline"`
	Status            string          `json:"status"`
	Type              string          `json:"type"`
	EpisodeRunTime    []int           `json:"episode_run_time"`
	NumberOfSeasons   int             `json:"number_of_seasons"`
	NumberOfEpisodes  int             `json:"number_of_episodes"`
	LastAirDate       string          `json:"last_air_date"`
	LastEpisodeToAir  *Episode        `json:"last_episode_to_air"`
	InProduction      bool            `json:"in_production"`
	Homepage          string          `json:"homepage"`
	Seasons           []SeasonSummary `json:"seasons"`
	Networks          []Network       `json:"networks"`
	ProductionCompany []Company       `json:"production_companies"`
	ProductionCountry []Country       `json:"production_countries"`
	CreatedBy         []struct {
		ID          int64  `json:"id"`
		Name        string `json:"name"`
		ProfilePath string `json:"profile_path"`
	} `json:"created_by"`
	Credits           *Credits        `json:"credits"`
	AggregateCredits  *Credits        `json:"aggregate_credits"`
	ContentRatings    *ContentRatings `json:"content_ratings"`
	ExternalIDs       *ExternalIDs    `json:"external_ids"`
	Images            *Images         `json:"images"`
	Keywords          *Keywords       `json:"keywords"`
	AlternativeTitles *AltTitles      `json:"alternative_titles"`
	Similar           *Paged[TVShow]  `json:"similar"`
	Recommendations   *Paged[TVShow]  `json:"recommendations"`
}

TVDetails is /tv/{id} with append_to_response.

type TVShow 

type TVShow struct {
	ID               int64    `json:"id"`
	Name             string   `json:"name"`
	OriginalName     string   `json:"original_name"`
	Overview         string   `json:"overview"`
	PosterPath       string   `json:"poster_path"`
	BackdropPath     string   `json:"backdrop_path"`
	FirstAirDate     string   `json:"first_air_date"`
	GenreIDs         []int    `json:"genre_ids"`
	Genres           []Genre  `json:"genres"`
	OriginCountry    []string `json:"origin_country"`
	OriginalLanguage string   `json:"original_language"`
	Popularity       float64  `json:"popularity"`
	VoteAverage      float64  `json:"vote_average"`
	VoteCount        int      `json:"vote_count"`
	Adult            bool     `json:"adult"`
	MediaType        string   `json:"media_type"`
}

TVShow is a list/search/discover TV item.

type UserListItem added in v0.3.3 

type UserListItem struct {
	ID        int64  `json:"id"`
	MediaType string `json:"media_type"`
}

type UserListPage added in v0.3.3 

type UserListPage struct {
	Page         int            `json:"page"`
	TotalPages   int            `json:"total_pages"`
	TotalResults int            `json:"total_results"`
	Results      []UserListItem `json:"results"`
	Items        []UserListItem `json:"items"`
}

UserListPage is one page of a public TMDB user list.

func GetUserListPage added in v0.3.3 

func GetUserListPage(ctx context.Context, client interface {
	GetJSON(context.Context, string, url.Values, any) error
}, id int64, page int) (UserListPage, error)

GetUserListPage retrieves a page through a rate-limited TMDB JSON client.

type Video 

type Video struct {
	ID          string `json:"id"`
	ISO639      string `json:"iso_639_1"`
	ISO3166     string `json:"iso_3166_1"`
	Key         string `json:"key"`
	Name        string `json:"name"`
	Site        string `json:"site"`
	Size        int    `json:"size"` // vertical resolution, e.g. 1080
	Type        string `json:"type"` // Trailer, Teaser, Clip, Featurette, ...
	Official    bool   `json:"official"`
	PublishedAt string `json:"published_at"`
}

Video is one TMDB /videos result: a trailer, teaser or other clip hosted on an external site (usually YouTube or Vimeo). Key is the site-specific video id, not a playable URL.

func (Video) Published 

func (v Video) Published() time.Time

Published parses PublishedAt (zero when empty or invalid).

type Videos 

type Videos struct {
	ID      int64   `json:"id"`
	Results []Video `json:"results"`
}

Videos is a /videos response.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.