A Swift Package for The Movie Database (TMDb) https://www.themoviedb.org
- Comprehensive API Coverage: Full support for TMDb API v3 with 17 specialized services
- Movie & TV Data: Details, credits, images, videos, reviews, recommendations, similar content
- Discovery & Search: Advanced filtering, multi-type search, trending content
- User Features: Account management, favorites, watchlists, ratings (requires authentication)
- Metadata: Genres, certifications, companies, collections, watch providers
- Image Generation: Built-in URL generation for all image types with size optimization
- Swift 6 Ready: Full strict concurrency support with Sendable types
- Cross-Platform: iOS 16+, macOS 13+, watchOS 9+, tvOS 16+, visionOS 1+, Linux, Windows
- Modern Swift: Async/await throughout, strongly-typed models, protocol-based architecture
| Service | Description |
|---|---|
| movies | Movie details, credits, images, videos, reviews, |
| recommendations, similar, releases, watch providers | |
| tvSeries | TV show details, credits, images, videos, reviews, |
| recommendations, similar, watch providers | |
| tvSeasons | Season-specific details, credits, images, videos |
| tvEpisodes | Episode-specific details, credits, images, videos |
| people | Person details, movie/TV credits, images |
| search | Multi-search across movies, TV shows, people, |
| collections, companies, keywords | |
| discover | Advanced filtering for movies and TV shows with 30+ |
| filter options | |
| trending | Trending movies, TV shows, and people (daily/weekly) |
| account | User favorites, watchlist, rated items |
| (requires authentication) | |
| authentication | Session management, guest sessions, request tokens |
| genres | Genre lists for movies and TV shows |
| watchProviders | Streaming availability by region |
| certifications | Content ratings (G, PG, R, etc.) |
| collections | Movie collection details and metadata |
| companies | Production company information |
| lists | Custom list management (requires authentication) |
| configurations | API configuration and image URL generation |
See the full API documentation for detailed usage.
- Swift 6.0+
- OS
- macOS 13+
- iOS 16+
- watchOS 9+
- tvOS 16+
- visionOS 1+
- Windows
- Linux
Add the TMDb package as a dependency to your Package.swift file, and add it
as a dependency to your target.
// swift-tools-version:5.9
import PackageDescription
let package = Package(
name: "MyProject",
dependencies: [
.package(url: "https://github.com/adamayoung/TMDb.git", from: "14.0.0")
],
targets: [
.target(name: "MyProject", dependencies: ["TMDb"])
]
)Add the TMDb package to your Project's Package dependencies.
Create an API key from The Movie Database web site https://www.themoviedb.org/documentation/api.
import TMDb
// Initialize client
let tmdbClient = TMDbClient(apiKey: "<your-tmdb-api-key>")
// Discover movies with filters
let popularMovies = try await tmdbClient.discover.movies(
sortedBy: .popularity(descending: true)
).results
// Get movie details
let fightClub = try await tmdbClient.movies.details(forMovie: 550)
print("Title: \(fightClub.title)")
print("Release Date: \(fightClub.releaseDate)")
print("Rating: \(fightClub.voteAverage)/10")
// Search across movies, TV shows, and people
let searchResults = try await tmdbClient.search.multi(query: "Breaking Bad")
// Get trending movies today
let trendingMovies = try await tmdbClient.trending.movies(inTimeWindow: .day)
// Get streaming providers for a movie
let watchProviders = try await tmdbClient.movies.watchProviders(forMovie: 550)
if let usProvider = watchProviders.first(where: { $0.countryCode == "US" }) {
print("Available on: \(usProvider.watchProviders.flatRate?.map(\.providerName) ?? [])")
}
// Generate poster image URL
let config = try await tmdbClient.configurations.apiConfiguration()
if let posterPath = fightClub.posterPath {
let posterURL = config.images.posterURL(for: posterPath, idealWidth: 500)
}By default, the TMDb client automatically uses your system's language and
country settings from Locale.current:
import TMDb
// Uses system locale automatically (recommended)
let tmdbClient = TMDbClient(apiKey: "<your-api-key>")You can also configure the client with custom language and country settings:
// Custom configuration
let configuration = TMDbConfiguration(
defaultLanguage: "es-ES", // ISO 639-1 language code
defaultCountry: "ES" // ISO 3166-1 country code
)
let tmdbClient = TMDbClient(apiKey: "<your-api-key>", configuration: configuration)
// Disable locale defaults (API determines language)
let tmdbClient = TMDbClient(apiKey: "<your-api-key>", configuration: .default)Per-request overrides are always available:
// Override language for a specific request
let movieInFrench = try await tmdbClient.movies.details(forMovie: 550, language: "fr")let movie = try await tmdbClient.movies.details(forMovie: movieId)
let credits = try await tmdbClient.movies.credits(forMovie: movieId)
let images = try await tmdbClient.movies.images(forMovie: movieId)let movies = try await tmdbClient.discover.movies(
sortedBy: .popularity(descending: true),
withGenres: [28, 12], // Action & Adventure
releaseDateGTE: Date().addingTimeInterval(-365*24*60*60) // Last year
)let providers = try await tmdbClient.movies.watchProviders(forMovie: movieId)
if let usProvider = providers.first(where: { $0.countryCode == "US" }) {
print("Available on: \(usProvider.watchProviders.flatRate?.map(\.providerName) ?? [])")
}// Add to favorites
try await tmdbClient.account.addToFavourites(movie: movieId, accountId: accountId)
// Rate a movie
try await tmdbClient.movies.addRating(8.5, toMovie: movieId)
// Get watchlist
let watchlist = try await tmdbClient.account.movieWatchlist(accountId: accountId)Documentation and examples of usage can be found at https://adamayoung.github.io/TMDb/documentation/tmdb/
- TMDb API Documentation
- Swift Package Index
- Full API Reference
- Getting Started Guide
- Image URL Generation Guide
Xcode 16.0+ Swift 6.0+ Homebrew
Install homebrew and the following formulae
brew install swiftlint swiftformat markdownlintSee CLAUDE.md for comprehensive development guidelines including:
- Testing requirements (unit and integration tests)
- Code style enforcement with swift-format
- DocC documentation requirements
- Complete CI check commands
Quick reference:
make format # Auto-format code
make lint # Check code style
make test # Run unit tests
make ci # Full CI validationImportant: Both unit tests AND integration tests must pass. Integration tests require these environment variables:
TMDB_API_KEY- Your TMDb API keyTMDB_USERNAME- Your TMDb usernameTMDB_PASSWORD- Your TMDB password
Running unit tests on Linux requires Docker to be running.
- The Movie Database (TMDb) for providing the comprehensive movie and TV data API
- JustWatch for watch provider data
- All contributors who have helped improve this library
Disclaimer: This product uses the TMDb API but is not endorsed or certified by TMDb.
This library is licensed under the Apache License 2.0. See LICENSE for details.