{"id":27764941,"url":"https://github.com/adamayoung/tmdb","last_synced_at":"2026-01-24T03:17:38.301Z","repository":{"id":37090910,"uuid":"251330206","full_name":"adamayoung/TMDb","owner":"adamayoung","description":"The Movie Database Swift Package","archived":false,"fork":false,"pushed_at":"2025-01-03T11:41:21.000Z","size":1607,"stargazers_count":131,"open_issues_count":3,"forks_count":34,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-06T06:34:58.628Z","etag":null,"topics":["actors","films","movie","movies","reviews","swift","swiftpm","themoviedatabase","themoviedb","tmdb","tmdb-api","tmdb-movie","tmdb-movie-search","tmdbapi","tv"],"latest_commit_sha":null,"homepage":"https://adamayoung.github.io/TMDb/documentation/tmdb","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adamayoung.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-03-30T14:28:05.000Z","updated_at":"2025-03-14T07:44:22.000Z","dependencies_parsed_at":"2024-01-22T20:47:52.467Z","dependency_job_id":"7105b242-e44a-43cf-8dc7-01badebc6c74","html_url":"https://github.com/adamayoung/TMDb","commit_stats":{"total_commits":77,"total_committers":3,"mean_commits":"25.666666666666668","dds":"0.051948051948051965","last_synced_commit":"a81647fb3a1d12e7187adcb86c90cb08d5efe4a2"},"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamayoung%2FTMDb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamayoung%2FTMDb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamayoung%2FTMDb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adamayoung%2FTMDb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adamayoung","download_url":"https://codeload.github.com/adamayoung/TMDb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251528787,"owners_count":21603876,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actors","films","movie","movies","reviews","swift","swiftpm","themoviedatabase","themoviedb","tmdb","tmdb-api","tmdb-movie","tmdb-movie-search","tmdbapi","tv"],"created_at":"2025-04-29T15:26:43.011Z","updated_at":"2026-01-24T03:17:38.296Z","avatar_url":"https://github.com/adamayoung.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TMDb - The Movie Database\n\n[![CI](https://github.com/adamayoung/TMDb/actions/workflows/ci.yml/badge.svg)](https://github.com/adamayoung/TMDb/actions/workflows/ci.yml)\n[![Integration](https://github.com/adamayoung/TMDb/actions/workflows/integration.yml/badge.svg)](https://github.com/adamayoung/TMDb/actions/workflows/integration.yml)\n[![CodeQL](https://github.com/adamayoung/TMDb/actions/workflows/codeql.yml/badge.svg)](https://github.com/adamayoung/TMDb/actions/workflows/codeql.yml)\n[![Documentation](https://github.com/adamayoung/TMDb/actions/workflows/documentation.yml/badge.svg)](https://github.com/adamayoung/TMDb/actions/workflows/documentation.yml)\n[![codecov](https://codecov.io/gh/adamayoung/TMDb/graph/badge.svg?token=TICHRASF6F)](https://codecov.io/gh/adamayoung/TMDb)\n[![Swift 6.0+](https://img.shields.io/badge/Swift-6.0+-orange.svg)](https://swift.org)\n[![Platforms](https://img.shields.io/badge/Platforms-iOS%20|%20macOS%20|%20watchOS%20|%20tvOS%20|%20visionOS%20|%20Linux%20|%20Windows-blue.svg)](https://github.com/adamayoung/TMDb)\n[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)\n\nA Swift Package for The Movie Database (TMDb) \u003chttps://www.themoviedb.org\u003e\n\n## Features\n\n* **Comprehensive API Coverage**: Full support for TMDb API v3 with 17\n  specialized services\n* **Movie \u0026 TV Data**: Details, credits, images, videos, reviews,\n  recommendations, similar content\n* **Discovery \u0026 Search**: Advanced filtering, multi-type search,\n  trending content\n* **User Features**: Account management, favorites, watchlists, ratings\n  (requires authentication)\n* **Metadata**: Genres, certifications, companies, collections, watch\n  providers\n* **Image Generation**: Built-in URL generation for all image types with\n  size optimization\n* **Swift 6 Ready**: Full strict concurrency support with Sendable types\n* **Cross-Platform**: iOS 16+, macOS 13+, watchOS 9+, tvOS 16+,\n  visionOS 1+, Linux, Windows\n* **Modern Swift**: Async/await throughout, strongly-typed models,\n  protocol-based architecture\n\n## Available Services\n\n| Service | Description |\n| ------- | ----------- |\n| **movies** | Movie details, credits, images, videos, reviews, |\n| | recommendations, similar, releases, watch providers |\n| **tvSeries** | TV show details, credits, images, videos, reviews, |\n| | recommendations, similar, watch providers |\n| **tvSeasons** | Season-specific details, credits, images, videos |\n| **tvEpisodes** | Episode-specific details, credits, images, videos |\n| **people** | Person details, movie/TV credits, images |\n| **search** | Multi-search across movies, TV shows, people, |\n| | collections, companies, keywords |\n| **discover** | Advanced filtering for movies and TV shows with 30+ |\n| | filter options |\n| **trending** | Trending movies, TV shows, and people (daily/weekly) |\n| **account** | User favorites, watchlist, rated items |\n| | (requires authentication) |\n| **authentication** | Session management, guest sessions, request tokens |\n| **genres** | Genre lists for movies and TV shows |\n| **watchProviders** | Streaming availability by region |\n| **certifications** | Content ratings (G, PG, R, etc.) |\n| **collections** | Movie collection details and metadata |\n| **companies** | Production company information |\n| **lists** | Custom list management (requires authentication) |\n| **configurations** | API configuration and image URL generation |\n\nSee the [full API documentation](https://adamayoung.github.io/TMDb/documentation/tmdb/)\nfor detailed usage.\n\n## Requirements\n\n* Swift 6.0+\n* OS\n  * macOS 13+\n  * iOS 16+\n  * watchOS 9+\n  * tvOS 16+\n  * visionOS 1+\n  * Windows\n  * Linux\n\n## Installation\n\n### [Swift Package Manager](https://github.com/apple/swift-package-manager)\n\nAdd the TMDb package as a dependency to your `Package.swift` file, and add it\nas a dependency to your target.\n\n```swift\n// swift-tools-version:5.9\n\nimport PackageDescription\n\nlet package = Package(\n  name: \"MyProject\",\n\n  dependencies: [\n    .package(url: \"https://github.com/adamayoung/TMDb.git\", from: \"14.0.0\")\n  ],\n\n  targets: [\n    .target(name: \"MyProject\", dependencies: [\"TMDb\"])\n  ]\n)\n```\n\n### Xcode project\n\nAdd the TMDb package to your Project's Package dependencies.\n\n## Setup\n\n### Get an API Key\n\nCreate an API key from The Movie Database web site\n[https://www.themoviedb.org/documentation/api](https://www.themoviedb.org/documentation/api).\n\n### Quick Start\n\n```swift\nimport TMDb\n\n// Initialize client\nlet tmdbClient = TMDbClient(apiKey: \"\u003cyour-tmdb-api-key\u003e\")\n\n// Discover movies with filters\nlet popularMovies = try await tmdbClient.discover.movies(\n    sortedBy: .popularity(descending: true)\n).results\n\n// Get movie details\nlet fightClub = try await tmdbClient.movies.details(forMovie: 550)\nprint(\"Title: \\(fightClub.title)\")\nprint(\"Release Date: \\(fightClub.releaseDate)\")\nprint(\"Rating: \\(fightClub.voteAverage)/10\")\n\n// Search across movies, TV shows, and people\nlet searchResults = try await tmdbClient.search.multi(query: \"Breaking Bad\")\n\n// Get trending movies today\nlet trendingMovies = try await tmdbClient.trending.movies(inTimeWindow: .day)\n\n// Get streaming providers for a movie\nlet watchProviders = try await tmdbClient.movies.watchProviders(forMovie: 550)\nif let usProvider = watchProviders.first(where: { $0.countryCode == \"US\" }) {\n    print(\"Available on: \\(usProvider.watchProviders.flatRate?.map(\\.providerName) ?? [])\")\n}\n\n// Generate poster image URL\nlet config = try await tmdbClient.configurations.apiConfiguration()\nif let posterPath = fightClub.posterPath {\n    let posterURL = config.images.posterURL(for: posterPath, idealWidth: 500)\n}\n```\n\n### Configuration\n\nBy default, the TMDb client automatically uses your system's language and\ncountry settings from `Locale.current`:\n\n```swift\nimport TMDb\n\n// Uses system locale automatically (recommended)\nlet tmdbClient = TMDbClient(apiKey: \"\u003cyour-api-key\u003e\")\n```\n\nYou can also configure the client with custom language and country settings:\n\n```swift\n// Custom configuration\nlet configuration = TMDbConfiguration(\n    defaultLanguage: \"es-ES\",  // ISO 639-1 language code\n    defaultCountry: \"ES\"       // ISO 3166-1 country code\n)\nlet tmdbClient = TMDbClient(apiKey: \"\u003cyour-api-key\u003e\", configuration: configuration)\n\n// Disable locale defaults (API determines language)\nlet tmdbClient = TMDbClient(apiKey: \"\u003cyour-api-key\u003e\", configuration: .default)\n```\n\nPer-request overrides are always available:\n\n```swift\n// Override language for a specific request\nlet movieInFrench = try await tmdbClient.movies.details(forMovie: 550, language: \"fr\")\n```\n\n## Common Use Cases\n\n### Displaying Movie Details\n\n```swift\nlet movie = try await tmdbClient.movies.details(forMovie: movieId)\nlet credits = try await tmdbClient.movies.credits(forMovie: movieId)\nlet images = try await tmdbClient.movies.images(forMovie: movieId)\n```\n\n### Building a Discover/Browse Interface\n\n```swift\nlet movies = try await tmdbClient.discover.movies(\n    sortedBy: .popularity(descending: true),\n    withGenres: [28, 12], // Action \u0026 Adventure\n    releaseDateGTE: Date().addingTimeInterval(-365*24*60*60) // Last year\n)\n```\n\n### Getting Watch Providers (Streaming Availability)\n\n```swift\nlet providers = try await tmdbClient.movies.watchProviders(forMovie: movieId)\nif let usProvider = providers.first(where: { $0.countryCode == \"US\" }) {\n    print(\"Available on: \\(usProvider.watchProviders.flatRate?.map(\\.providerName) ?? [])\")\n}\n```\n\n### User Account Features (Authentication Required)\n\n```swift\n// Add to favorites\ntry await tmdbClient.account.addToFavourites(movie: movieId, accountId: accountId)\n\n// Rate a movie\ntry await tmdbClient.movies.addRating(8.5, toMovie: movieId)\n\n// Get watchlist\nlet watchlist = try await tmdbClient.account.movieWatchlist(accountId: accountId)\n```\n\n## Documentation\n\nDocumentation and examples of usage can be found at\n[https://adamayoung.github.io/TMDb/documentation/tmdb/](https://adamayoung.github.io/TMDb/documentation/tmdb/)\n\n## Related Resources\n\n* [TMDb API Documentation](https://developer.themoviedb.org/docs)\n* [Swift Package Index](https://swiftpackageindex.com/adamayoung/TMDb)\n* [Full API Reference](https://adamayoung.github.io/TMDb/documentation/tmdb/)\n* [Getting Started Guide](https://adamayoung.github.io/TMDb/documentation/tmdb/creatingtmdbclient)\n* [Image URL Generation Guide](https://adamayoung.github.io/TMDb/documentation/tmdb/generatingimageurls)\n\n## Development\n\n### Prerequisites\n\nXcode 16.0+\nSwift 6.0+\nHomebrew\n\n#### Homebrew\n\nInstall [homebrew](https://brew.sh) and the following formulae\n\n* [swiftlint](https://github.com/realm/SwiftLint)\n* [swiftformat](https://github.com/nicklockwood/SwiftFormat)\n* [markdownlint](https://github.com/igorshubovych/markdownlint-cli)\n\n```bash\nbrew install swiftlint swiftformat markdownlint\n```\n\n### Before Submitting a PR\n\nSee [CLAUDE.md](CLAUDE.md) for comprehensive development guidelines including:\n\n* Testing requirements (unit and integration tests)\n* Code style enforcement with swift-format\n* DocC documentation requirements\n* Complete CI check commands\n\nQuick reference:\n\n```bash\nmake format        # Auto-format code\nmake lint          # Check code style\nmake test          # Run unit tests\nmake ci            # Full CI validation\n```\n\n**Important**: Both unit tests AND integration tests must pass.\nIntegration tests require these environment variables:\n\n* `TMDB_API_KEY` - Your TMDb API key\n* `TMDB_USERNAME` - Your TMDb username\n* `TMDB_PASSWORD` - Your TMDB password\n\nRunning unit tests on Linux requires [Docker](https://www.docker.com) to be running.\n\n## Acknowledgments\n\n* [The Movie Database (TMDb)](https://www.themoviedb.org) for providing\n  the comprehensive movie and TV data API\n* [JustWatch](https://www.justwatch.com) for watch provider data\n* All contributors who have helped improve this library\n\n**Disclaimer**: This product uses the TMDb API but is not endorsed or\ncertified by TMDb.\n\n## License\n\nThis library is licensed under the Apache License 2.0. See\n[LICENSE](https://github.com/adamayoung/TMDb/blob/main/LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadamayoung%2Ftmdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadamayoung%2Ftmdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadamayoung%2Ftmdb/lists"}