golib/tmdb

TMDB - v0.9.2

A Go client library for The Movie Database (TMDB) API with automatic rate limiting, retry logic, and convenient helper functions.

Features

• Clean interface for TMDB's REST API
• Automatic rate limiting with exponential backoff
• Retry logic for rate limit errors (respects Retry-After header)
• Movie search functionality
• Movie details retrieval
• Cast and crew information
• Image URL helpers
• Environment variable configuration with ConfigFromEnv
• EZConf integration for unified configuration
• Comprehensive test coverage (94.1%)

Installation

go get git.haelnorr.com/h/golib/tmdb

Quick Start

Basic Usage

package main

import (
    "fmt"
    "log"
    "git.haelnorr.com/h/golib/tmdb"
)

func main() {
    // Create API connection
    api, err := tmdb.NewAPIConnection()
    if err != nil {
        log.Fatal(err)
    }

    // Search for a movie
    results, err := api.SearchMovies("Fight Club", false, 1)
    if err != nil {
        log.Fatal(err)
    }

    for _, movie := range results.Results {
        fmt.Printf("%s (%s)\n", movie.Title, movie.ReleaseYear())
        fmt.Printf("Poster: %s\n", movie.GetPoster(&api.Image, "w500"))
    }
}

Getting Movie Details

// Get detailed information about a movie
movie, err := api.GetMovie(550) // Fight Club
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Title: %s\n", movie.Title)
fmt.Printf("Overview: %s\n", movie.Overview)
fmt.Printf("Release Date: %s\n", movie.ReleaseDate)
fmt.Printf("IMDb ID: %s\n", movie.IMDbID)
fmt.Printf("Rating: %.1f/10\n", movie.VoteAverage)

Getting Cast and Crew

// Get credits for a movie
credits, err := api.GetCredits(550)
if err != nil {
    log.Fatal(err)
}

fmt.Println("Cast:")
for _, actor := range credits.Cast {
    fmt.Printf("  %s as %s\n", actor.Name, actor.Character)
}

fmt.Println("\nDirector:")
for _, member := range credits.Crew {
    if member.Job == "Director" {
        fmt.Printf("  %s\n", member.Name)
    }
}

Configuration

Environment Variables

The package requires the following environment variable:

# TMDB API access token (required)
TMDB_TOKEN=your_api_token_here

Get your API token from: https://www.themoviedb.org/settings/api

Using EZConf Integration

import (
    "git.haelnorr.com/h/golib/ezconf"
    "git.haelnorr.com/h/golib/tmdb"
)

loader := ezconf.New()
loader.RegisterIntegration(tmdb.NewEZConfIntegration())
loader.Load()

// Get the configured API connection
api, ok := loader.GetConfig("tmdb")
if !ok {
    log.Fatal("tmdb config not found")
}

Rate Limiting

TMDB has rate limits around 40 requests per second. This package implements automatic retry logic with exponential backoff:

• Initial backoff: 1 second
• Exponential growth: 1s → 2s → 4s → 8s → 16s → 32s (max)
• Maximum retries: 3 attempts
• Respects Retry-After header when provided by the API

All API calls automatically handle rate limiting, so you don't need to worry about it.

Image URLs

The TMDB API provides base URLs for images. Use helper methods to construct full image URLs:

// Available poster sizes: "w92", "w154", "w185", "w342", "w500", "w780", "original"
posterURL := movie.GetPoster(&api.Image, "w500")

// Available backdrop sizes: "w300", "w780", "w1280", "original"
backdropURL := movie.GetBackdrop(&api.Image, "w1280")

// Available profile sizes: "w45", "w185", "h632", "original"
profileURL := actor.GetProfile(&api.Image, "w185")

API Reference

Main Functions

• NewAPIConnection() (*APIConnection, error) - Create a new API connection
• SearchMovies(query string, includeAdult bool, page int) (*SearchResponse, error) - Search for movies
• GetMovie(movieID int) (*Movie, error) - Get detailed movie information
• GetCredits(movieID int) (*Credits, error) - Get cast and crew information

Helper Methods

Movie Methods:

• ReleaseYear() string - Extract year from release date
• GetPoster(imgConfig *ImageConfig, size string) string - Get full poster URL
• GetBackdrop(imgConfig *ImageConfig, size string) string - Get full backdrop URL

Cast/Crew Methods:

• GetProfile(imgConfig *ImageConfig, size string) string - Get full profile image URL

Error Handling

The package returns wrapped errors for easy debugging:

data, err := api.SearchMovies("Inception", false, 1)
if err != nil {
    if strings.Contains(err.Error(), "rate limit exceeded") {
        // Handle rate limiting
    } else if strings.Contains(err.Error(), "unexpected status code: 401") {
        // Invalid API token
    } else if strings.Contains(err.Error(), "unexpected status code: 404") {
        // Resource not found
    } else {
        // Network or other errors
    }
}

Documentation

For detailed documentation, see the TMDB Wiki.

Additional API documentation is available at GoDoc.

Testing

Run the test suite (requires a valid TMDB_TOKEN environment variable):

export TMDB_TOKEN=your_api_token_here
go test -v ./...

Current test coverage: 94.1%

Best Practices

1. Reuse API connections - Create one connection and reuse it for multiple requests
2. Cache responses - Cache API responses when appropriate to reduce API calls
3. Use specific image sizes - Use appropriate image sizes instead of "original" to save bandwidth
4. Handle rate limits gracefully - The library handles this automatically, but be aware it may introduce delays
5. Set a timeout - Consider using context with timeout for long-running operations

Example Projects

Check out these projects using the TMDB library:

• Project ReShoot - Movie database application

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Related Projects

• ezconf - Unified configuration management
• hlog - Structured logging with zerolog

External Resources

• TMDB API Documentation
• Get API Token
• TMDB Website