{"id":13852866,"url":"https://github.com/ChrisKruegerDev/tmdb-kotlin","last_synced_at":"2025-07-13T09:31:28.699Z","repository":{"id":43477501,"uuid":"351336290","full_name":"ChrisKruegerDev/tmdb-kotlin","owner":"ChrisKruegerDev","description":"🎬 Modern powerful TMDB API to fetch movies and TV shows for Kotlin Multiplatform. ","archived":false,"fork":false,"pushed_at":"2024-11-18T17:46:01.000Z","size":1079,"stargazers_count":211,"open_issues_count":0,"forks_count":23,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-11-21T06:34:59.495Z","etag":null,"topics":["android","discover","kotlin","kotlin-js","kotlin-library","kotlin-multiplatform","kotlin-native","ktor","ktor-client","movie","multiplatform","poster","tmdb","tmdb-api","tmdb-data","tmdb-rest-api"],"latest_commit_sha":null,"homepage":"https://www.moviebase.app","language":"Kotlin","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/ChrisKruegerDev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-25T06:48:28.000Z","updated_at":"2024-11-18T17:41:54.000Z","dependencies_parsed_at":"2023-11-22T22:26:46.531Z","dependency_job_id":"41a478dd-8c78-43fb-bf09-d5ed8a4a4f2c","html_url":"https://github.com/ChrisKruegerDev/tmdb-kotlin","commit_stats":null,"previous_names":["moviebaseapp/tmdb-api","chriskruegerdev/tmdb-kotlin","moviebaseapp/tmdb-kotlin"],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisKruegerDev%2Ftmdb-kotlin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisKruegerDev%2Ftmdb-kotlin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisKruegerDev%2Ftmdb-kotlin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChrisKruegerDev%2Ftmdb-kotlin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ChrisKruegerDev","download_url":"https://codeload.github.com/ChrisKruegerDev/tmdb-kotlin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225868819,"owners_count":17537122,"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":["android","discover","kotlin","kotlin-js","kotlin-library","kotlin-multiplatform","kotlin-native","ktor","ktor-client","movie","multiplatform","poster","tmdb","tmdb-api","tmdb-data","tmdb-rest-api"],"created_at":"2024-08-04T23:00:26.743Z","updated_at":"2024-11-22T08:30:47.374Z","avatar_url":"https://github.com/ChrisKruegerDev.png","language":"Kotlin","funding_links":[],"categories":["Libraries"],"sub_categories":["🧩 Service SDK"],"readme":"[Website](https://www.themoviedb.org) |\n[Forum](https://www.themoviedb.org/talk/category/5047958519c29526b50017d6) |\n[Documentation](https://www.themoviedb.org/documentation/api) |\n[TMDB API 3](https://developers.themoviedb.org/3)\n\n\u003ca href=\"https://www.themoviedb.org\"\u003e\u003cimg alt=\"TMDb\" src=\"doc/images/blue_short.svg\" width=\"600\"\u003e\u003c/a\u003e\n\n***Get movies and TV shows from the largest community database.***\n\n[![Maven Central](https://img.shields.io/maven-central/v/app.moviebase/tmdb-api?label=Maven%20Central)](https://search.maven.org/artifact/app.moviebase/tmdb-api)\n![Github Actions](https://github.com/ChrisKruegerDev/tmdb-kotlin/actions/workflows/build.yml/badge.svg)\n[![Issues](https://img.shields.io/github/issues/ChrisKruegerDev/tmdb-kotlin)](https://github.com/ChrisKruegerDev/tmdb-api/issues)\n[![Kotlin](https://img.shields.io/badge/kotlin-2.0.21-blue.svg?logo=kotlin)](http://kotlinlang.org)\n[![Gradle](https://img.shields.io/badge/Gradle-8-green?style=flat)](https://gradle.org)\n[![GitHub License](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat)](http://www.apache.org/licenses/LICENSE-2.0)\n[![GitHub Account](https://img.shields.io/static/v1?label=GitHub\u0026message=ChrisKruegerDev\u0026color=C51162)](https://github.com/ChrisKruegerDev)\n\n\u003chr\u003e\n\n# TMDB Kotlin\nTMDB Kotlin is a **Kotlin Multiplatform** library for fetching movies, TV shows, episodes, and all relevant information.\n\n* Written in Kotlin native with ktor from the ground up.\n* Support for Android, iOS, desktop, and web applications.\n* High customizable HttpClient configuration\n\n\nSample projects:\n\n* [Moviebase](https://play.google.com/store/apps/details?id=com.moviebase)\n* [StreamGuide](https://play.google.com/store/apps/details?id=app.streamguide)\n* [tivi](https://github.com/chrisbanes/tivi)\n*\n## Adding to your project\n\nThe library is available on Maven Central.\n\n### Gradle\n\nAdd the Maven Central repository if it is not already there.\n\n```kotlin\nrepositories {\n    mavenCentral()\n}\n```\n\nTo use the library in a single-platform project, add a dependency.\n\n```kotlin\ndependencies {\n    implementation(\"app.moviebase:tmdb-api:1.4.0\")\n}\n```\n\nIn Kotlin Multiplatform projects, add the dependency to your commonMain source-set dependencies.\n\n```kotlin\ncommonMain {\n    dependencies {\n        implementation(\"app.moviebase:tmdb-api:1.4.0\")\n    }\n}\n```\n\n## Usage\nMost of the library follows the possibilities and naming at the [official documentation](https://www.themoviedb.org/documentation/api). The documentation of the API endpoints is on [version 3](https://developers.themoviedb.org/3) and [version 4](https://developers.themoviedb.org/4).\n\n### Configuration\nBuild up your TMDB instance to access the APIs. You can configure the entire HttpClient of ktor.\n\n```kotlin\nval tmdb = Tmdb3 {\n    tmdbApiKey = \"yourApiKey\"\n\n    userAuthentication {\n        authenticationToken = \"auth token for version 4\"\n        val storage = TmdbAccountStorage() // use own class here\n        loadSessionId { storage.sessionId  }\n        loadGuestSessionId { storage.guestSessionId }\n        loadAccessToken { storage.accessToken }\n    }\n\n    expectSuccess = false // if you want to disable exceptions\n    useCache = true\n    useTimeout = true\n    maxRetriesOnException = 3 // retries when network calls throw an exception\n\n    // add your own client\n    httpClient(OkHttp) {\n        engine {\n\n        }\n    }\n\n    httpClient {\n        // for custom HttpClient configuration\n    }\n}\n```\n\nYou need to add your own TMDB API key for using the library. The instruction for the creation is in the [TMDB developer guide](https://developers.themoviedb.org).\n\n\n### Get information\nFor getting basic information about a movie or other media content.\n\n```kotlin\nval tmdb = Tmdb3(\"apiKey\")\nval movieDetail = tmdb.movies.getDetails(\n    movieId = 12,\n    language = \"DE\",\n    appendResponses = listOf(AppendResponse.MOVIE_CREDITS)\n)\n```\n\n### Search\nSearch for TV shows by a query.\n\n```kotlin\nval tmdb = Tmdb3(\"apiKey\")\nval showPageResult = tmdb.search.findShows(\n    query = \"The Expanse\",\n    page = 1,\n    language = \"DE\",\n    region = \"US\",\n    includeAdult = false\n)\n```\n\n\n### Discover\nDiscover a movie or TV show by the discover parameter class.\n\n```kotlin\nval discover = TmdbDiscover.Movie(\n    sortBy = TmdbDiscoverMovieSortBy.POPULARITY,\n    sortOrder = TmdbSortOrder.DESC,\n    voteAverageGte = 5,\n    voteCountGte = 200,\n    releaseDate = TmdbDiscoverTimeRange.BetweenYears(from = 2020, to = 2021)\n)\n\nval discoverPageResult = tmdb.discover.discoverMovie(\n    page = 1,\n    region = \"DE\",\n    language = \"de\",\n    discover = discover\n)\n```\n\nAlternatively, use predefined discover categories like upcoming, networks or on streaming.\n\n```kotlin\nval discoverCategory = DiscoverCategory.OnStreaming.Netflix(\n    mediaType = TmdbMediaType.MOVIE,\n    watchRegion = \"DE\"\n)\n\nval result = tmdb.discover.discoverByCategory(\n    page = 1,\n    region = \"DE\",\n    language = \"de\",\n    category = discoverCategory\n)\n```\n\n### Authentication\nBuild up your authentication URL, which you can open in the web view.\n\n```kotlin\n// Returns \"https://www.themoviedb.org/authenticate/[request_token]?redirect_to=auth://yourApp\"\nval url = tmdb.authentication.requestAuthorizationUrl(\"auth://yourApp\")\n```\nAfter opening the URL, TMDB version 3 returns the following URL:\n```kotlin\nyourApp://auth/login?request_token=[request_token]\u0026approved=true\n```\n\n\n### Build image URL\n\nYou can build an image URL via the poster file path and size key. More information on the [TMDB images site](https://developers.themoviedb.org/3/getting-started/images).\n\n```kotlin\nval url = TmdbImageUrlBuilder.build(\"nBNZadXqJSdt05SHLqgT0HuC5Gm.jpg\", \"w154\")\n```\n\nOr create the URL by an image class with the best matched width/height.\n\n```kotlin\nval url = TmdbImageUrlBuilder.build(image = movie.posterImage, width = 200, height = 300)\n```\n\nFor creating the poster URL by the movie item.\n\n```kotlin\nval url = TmdbImageUrlBuilder.buildPoster(item = movie, width = 200)\n```\n\n### Build video URL\n\nYou can build a video URL by the key value into `TmdbVideo`. TMDb API currently support videos from YouTube and Vimeo\n\n```kotlin\nval youtubeTmdbVideo = TmdbVideo(id = \"123\", key = \"qwerasdf\", site = TmdbVideoSite.YOUTUBE)\nval url = TmdbImageUrlBuilder.build(youtubeTmdbVideo) // It will return `https://www.youtube.com/watch?v=qwerasdf`\n\nval vimeoTmdbVideo = TmdbVideo(id = \"123\", key = \"qwerasdf\", site = TmdbVideoSite.VIMEO)\nval url = TmdbImageUrlBuilder.build(vimeoTmdbVideo) // It will return `https://vimeo.com/qwerasdf`\n```\n## Contributing 🤝\nPlease feel free to [open an issue](https://github.com/ChrisKruegerDev/tmdb-kotlin/issues/new/choose) if you have any questions or suggestions. Or participate in the [discussion](https://github.com/ChrisKruegerDev/tmdb-kotlin/discussions). If you want to contribute, please read the [contribution guidelines](https://github.com/ChrisKruegerDev/tmdb-kotlin/blob/main/CONTRIBUTING.md) for more information.\n\n\u003cbr\u003e\n\n\u003chr\u003e\n\n*This library uses the TMDB but is not endorsed or certified by TMDB. These services are licensed under [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0).*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FChrisKruegerDev%2Ftmdb-kotlin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FChrisKruegerDev%2Ftmdb-kotlin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FChrisKruegerDev%2Ftmdb-kotlin/lists"}