This is a Golang wrapper around the TMDb API, forked from cyruzin/golang-tmdb.

An API Key is required. To register for one, head over to themoviedb.org.

This product uses the TMDb API but is not endorsed or certified by TMDb.

Fork

This is a fork of cyruzin/golang-tmdb. It is a drop-in replacement: the client is built with functional options (tmdb.New(tmdb.WithAPIKey(...))) instead of the Init and InitV4 constructors, and the request path retries 429s with tmdb.WithAutoRetry(). Endpoint methods and their signatures are unchanged.

It has its own module path, so it is a plain dependency rather than something a replace points at:

go get src.timharek.no/tim/tmdb-go

import tmdb "src.timharek.no/tim/tmdb-go"

Coming from upstream, the import path is the only thing that changes.

If your code calls Init or InitV4, switch to the equivalent option:

-tmdbClient, err := tmdb.Init(os.Getenv("YOUR_APIKEY"))
+tmdbClient, err := tmdb.New(tmdb.WithAPIKey(os.Getenv("YOUR_APIKEY")))

-tmdbClient, err := tmdb.InitV4(os.Getenv("YOUR_BEARER_TOKEN"))
+tmdbClient, err := tmdb.New(tmdb.WithBearerToken(os.Getenv("YOUR_BEARER_TOKEN")))

Requirements

• Go 1.27.x or higher. We aim to support the latest supported versions of go.

Installation

go get -u github.com/cyruzin/golang-tmdb

See Fork above for using this fork instead of upstream.

Usage

To get started, create a new client. The import is github.com/cyruzin/golang-tmdb in both cases — with upstream it resolves to the upstream module, with this fork it resolves through the replace:

import "github.com/cyruzin/golang-tmdb"

// With API key (v3 authentication)
tmdbClient, err := tmdb.New(tmdb.WithAPIKey(os.Getenv("YOUR_APIKEY")))
if err != nil {
    fmt.Println(err)
}

// With bearer token (v4 authentication)
tmdbClient, err := tmdb.New(tmdb.WithBearerToken(os.Getenv("YOUR_BEARER_TOKEN")))
if err != nil {
    fmt.Println(err)
}

movie, err := tmdbClient.GetMovieDetails(297802, nil)
if err != nil {
    fmt.Println(err)
}

fmt.Println(movie.Title)

Client Options

The client supports functional options for configuration:

// Auto retry on rate limit (429 TOO MANY REQUESTS)
tmdbClient, err := tmdb.New(
    tmdb.WithAPIKey(os.Getenv("YOUR_APIKEY")),
    tmdb.WithAutoRetry(),
)

// Custom timeout (default is 10 seconds)
tmdbClient, err := tmdb.New(
    tmdb.WithAPIKey(os.Getenv("YOUR_APIKEY")),
    tmdb.WithTimeout(time.Second * 5),
)

// Alternate base URL (https://api.tmdb.org/3 instead of https://api.themoviedb.org/3)
tmdbClient, err := tmdb.New(
    tmdb.WithAPIKey(os.Getenv("YOUR_APIKEY")),
    tmdb.WithAlternateBaseURL(),
)

// Custom base URL (useful for testing)
tmdbClient, err := tmdb.New(
    tmdb.WithAPIKey(os.Getenv("YOUR_APIKEY")),
    tmdb.WithCustomBaseURL("http://localhost:3000"),
)

// Custom http.Client configuration
customClient := http.Client{
    Timeout: time.Second * 5,
    Transport: &http.Transport{
        MaxIdleConns:    10,
        IdleConnTimeout: 15 * time.Second,
    },
}
tmdbClient, err := tmdb.New(
    tmdb.WithAPIKey(os.Getenv("YOUR_APIKEY")),
    tmdb.WithHTTPClient(customClient),
)

// Session ID for authenticated endpoints
// https://developers.themoviedb.org/3/authentication/how-do-i-generate-a-session-id
tmdbClient, err := tmdb.New(
    tmdb.WithAPIKey(os.Getenv("YOUR_APIKEY")),
    tmdb.WithSessionID(os.Getenv("YOUR_SESSION_ID")),
)

Request Options

Pass optional parameters to endpoints:

options := map[string]string{
    "language":           "pt-BR",
    "append_to_response": "credits,images",
}

movie, err := tmdbClient.GetMovieDetails(297802, options)
if err != nil {
    fmt.Println(err)
}

fmt.Println(movie.Title)

Helpers

Generate image and video URLs:

options := map[string]string{
    "append_to_response": "videos",
}

movie, err := tmdbClient.GetMovieDetails(297802, options)
if err != nil {
    fmt.Println(err)
}

fmt.Println(tmdb.GetImageURL(movie.BackdropPath, tmdb.W500))
// Output: https://image.tmdb.org/t/p/w500/bOGkgRGdhrBYJSLpXaxhXVstddV.jpg
fmt.Println(tmdb.GetImageURL(movie.PosterPath, tmdb.Original))
// Output: https://image.tmdb.org/t/p/original/bOGkgRGdhrBYJSLpXaxhXVstddV.jpg

for _, video := range movie.Videos.Results {
    if video.Key != "" {
        fmt.Println(tmdb.GetVideoURL(video.Key))
        // Output: https://www.youtube.com/watch?v=6ZfuNTqbHE8
    }
}

For more examples, see the examples directory.

Performance

Getting Movie Details:

Iterations	ns/op	B/op	allocs/op
19	60886648	60632	184

Multi Search:

Iterations	ns/op	B/op	allocs/op
16	66596963	107109	608

Contributing

To start contributing, please check CONTRIBUTING.

Tests

For local testing, just run:

 mise run test

Most of the tests call the live TMDb API, so CI runs mise run test:short, which covers only the tests that need no network.

License

MIT