Library for fetching movies, TV shows, and related information from a comprehensive community database. Features customizable HttpClient configuration, search, discovery, and authentication functionalities.
Website | Forum | Documentation | TMDB API 3
Get movies and TV shows from the largest community database.
TMDB Kotlin is a Kotlin Multiplatform library for fetching movies, TV shows, episodes, and all relevant information.
Sample projects:
The library is available on Maven Central.
Add the Maven Central repository if it is not already there.
repositories {
mavenCentral()
}
To use the library in a single-platform project, add a dependency.
dependencies {
implementation("app.moviebase:tmdb-api:1.5.0")
}
In Kotlin Multiplatform projects, add the dependency to your commonMain source-set dependencies.
commonMain {
dependencies {
implementation("app.moviebase:tmdb-api:1.5.0")
}
}
Most of the library follows the possibilities and naming at the official documentation. The documentation of the API endpoints is on version 3 and version 4.
Build up your TMDB instance to access the APIs. You can configure the entire HttpClient of ktor.
val tmdb = Tmdb3 {
tmdbApiKey = "yourApiKey"
userAuthentication {
authenticationToken = "auth token for version 4"
val storage = TmdbAccountStorage() // use own class here
loadSessionId { storage.sessionId }
loadGuestSessionId { storage.guestSessionId }
loadAccessToken { storage.accessToken }
}
expectSuccess = false // if you want to disable exceptions
useCache = true
useTimeout = true
maxRetriesOnException =
httpClient(OkHttp) {
engine {
}
}
httpClient {
}
}
You need to add your own TMDB API key for using the library. The instruction for the creation is in the TMDB developer guide.
For getting basic information about a movie or other media content.
val tmdb = Tmdb3("apiKey")
val movieDetail = tmdb.movies.getDetails(
movieId = 12,
language = "DE",
appendResponses = listOf(AppendResponse.MOVIE_CREDITS)
)
Search for TV shows by a query.
val tmdb = Tmdb3("apiKey")
val showPageResult = tmdb.search.findShows(
query = "The Expanse",
page = 1,
language = "DE",
region = "US",
includeAdult = false
)
Discover a movie or TV show by the discover parameter class.
val discover = TmdbDiscover.Movie(
sortBy = TmdbDiscoverMovieSortBy.POPULARITY,
sortOrder = TmdbSortOrder.DESC,
voteAverageGte = 5,
voteCountGte = 200,
releaseDate = TmdbDiscoverTimeRange.BetweenYears(from = 2020, to = 2021)
)
val discoverPageResult = tmdb.discover.discoverMovie(
page = 1,
region = "DE",
language = "de",
discover = discover
)
Alternatively, use predefined discover categories like upcoming, networks or on streaming.
val discoverCategory = DiscoverCategory.OnStreaming.Netflix(
mediaType = TmdbMediaType.MOVIE,
watchRegion = "DE"
)
val result = tmdb.discover.discoverByCategory(
page = 1,
region = "DE",
language = "de",
category = discoverCategory
)
Build up your authentication URL, which you can open in the web view.
// Returns "https://www.themoviedb.org/authenticate/[request_token]?redirect_to=auth://yourApp"
val url = tmdb.authentication.requestAuthorizationUrl("auth://yourApp")
After opening the URL, TMDB version 3 returns the following URL:
yourApp://auth/login?request_token=[request_token]&approved=true
You can build an image URL via the poster file path and size key. More information on the TMDB images site.
val url = TmdbImageUrlBuilder.build("nBNZadXqJSdt05SHLqgT0HuC5Gm.jpg", "w154")
Or create the URL by an image class with the best matched width/height.
val url = TmdbImageUrlBuilder.build(image = movie.posterImage, width = 200, height = 300)
For creating the poster URL by the movie item.
val url = TmdbImageUrlBuilder.buildPoster(item = movie, width = 200)
You can build a video URL by the key value into TmdbVideo. TMDb API currently support videos from YouTube and Vimeo
val youtubeTmdbVideo = TmdbVideo(id = "123", key = "qwerasdf", site = TmdbVideoSite.YOUTUBE)
val url = TmdbImageUrlBuilder.build(youtubeTmdbVideo) // It will return `https://www.youtube.com/watch?v=qwerasdf`
val vimeoTmdbVideo = TmdbVideo(id = "123", key = "qwerasdf", site = TmdbVideoSite.VIMEO)
val url = TmdbImageUrlBuilder.build(vimeoTmdbVideo) // It will return `https://vimeo.com/qwerasdf`
Please feel free to open an issue if you have any questions or suggestions. Or participate in the discussion. If you want to contribute, please read the contribution guidelines for more information.
This library uses the TMDB but is not endorsed or certified by TMDB. These services are licensed under CC BY-NC 4.0.
Surfaced from shared tags and platforms — no rankings paid for.