drewcarlson / tmdb-api

This Kotlin Multiplatform library is for accessing the TMDB API to get movie and TV show content. Using for Android, iOS, and JS projects.

Website | Forum | Documentation | TMDb 3 API

Get movie and TV show content from TMDb in a fast and simple way.

---

TMDb API

This library gives access to TMDb API version 3 and 4 for mobile, desktop, and web applications. It supports Swift, Kotlin, and JavaScript by setting up as a Kotlin Multiplatform project.

This library is mainly used and supported by Moviebase.

Adding to your project

The library is available on Maven Central.

Gradle

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:0.6.3")
}

In Kotlin Multiplatform projects, add the dependency to your commonMain source-set dependencies.

commonMain {
    dependencies {
        implementation("app.moviebase:tmdb-api:0.6.3")
    }
}

Maven

Add a dependency to the <dependencies> element.

<dependency>
    <groupId>app.moviebase</groupId>
    <artifactId>tmdb-api</artifactId>
    <version>0.6.3</version>
</dependency>

Usage

Most of the library follows the possibilities and naming at the official TMDb documentation.

The documentation of the endpoints can be found in Version 3 and Version 4.

Get information

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

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

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 image URL

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)

Build video URL

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`

---

This library uses the TMDb but is not endorsed or certified by TMDb. These services are licensed under CC BY-NC 4.0.