{"id":13580901,"url":"https://github.com/grantholle/moviedb-promise","last_synced_at":"2026-01-06T01:54:12.301Z","repository":{"id":27634370,"uuid":"114721059","full_name":"grantholle/moviedb-promise","owner":"grantholle","description":"Interact with themoviedb.org's api with Node... now in TypeScript!","archived":false,"fork":false,"pushed_at":"2024-07-12T05:47:08.000Z","size":573,"stargazers_count":224,"open_issues_count":3,"forks_count":49,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-03-08T02:09:43.221Z","etag":null,"topics":["hacktoberfest","themoviedb","tmdb","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grantholle.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-12-19T05:01:08.000Z","updated_at":"2025-01-25T13:45:42.000Z","dependencies_parsed_at":"2024-01-16T20:31:22.183Z","dependency_job_id":"baecd0c4-617d-42fa-a35a-376d869230b0","html_url":"https://github.com/grantholle/moviedb-promise","commit_stats":{"total_commits":318,"total_committers":23,"mean_commits":"13.826086956521738","dds":"0.22012578616352196","last_synced_commit":"995116786a6e2fed4a36cdaa63b84f6a794bbfeb"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grantholle%2Fmoviedb-promise","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grantholle%2Fmoviedb-promise/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grantholle%2Fmoviedb-promise/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grantholle%2Fmoviedb-promise/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grantholle","download_url":"https://codeload.github.com/grantholle/moviedb-promise/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247445651,"owners_count":20939952,"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":["hacktoberfest","themoviedb","tmdb","typescript"],"created_at":"2024-08-01T15:01:56.083Z","updated_at":"2026-01-06T01:54:12.249Z","avatar_url":"https://github.com/grantholle.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# moviedb-promise\n\n[![npm](https://img.shields.io/npm/dw/moviedb-promise.svg?style=for-the-badge)](https://www.npmjs.com/package/moviedb-promise)\n\nA Node library that makes the interaction with themoviedb.org V3 API easy... Now in TypeScript!\n\nThis was originally a pull request that went stale, so it's its own package now. The original package developed by [Dan Zajdband](https://github.com/impronunciable) uses callbacks to handle the asynchronous nature of Node, while this package uses native Promises.\n\nThe main credit goes to the [original `moviedb` package](https://github.com/impronunciable/moviedb) by Dan Zajdband.\n\n## What is themoviedb.org?\n\nThe Movie Database (TMDB) is a community built project that stores data about movies and television shows. The project started in 2008 and has become one of the largest databases in the world. There are few databases with the vast data TMDB provides. In addition, TMDB gives special attention to international content which is often difficult to find on other databases. TMDB supports 39 different languages and is currently used in 180 countries.\n\nIn addition to information about actors, directors, production years, movie titles, genres, etc., TMDB also provides high resolution posters and fanart that can easily be incorporated into personal projects. The size of the image database is vast and growing at a rate of 1000 images a day. TMDB processes over 3 billion requests by millions of users daily.\n\nThe vast amount of data gathered and stored by TMDB can be accessed via its API. With a key and a URL, making a request is simple. However, managing all the requests needed to create say, a movie rating website, would be quite the task. You'd have to create a function for every type of request needed. That's where moviedb-promise comes in. With it's suite of over 100 functions, moviedb-promise makes interacting with TMDB easy.\n\n## Changelog for v4\n\n- Updated dependencies that may not support lower versions of Node\n- Implemented a throttle for Cloudflare rate limiting ([#72](https://github.com/grantholle/moviedb-promise/pull/74)) (thanks [@alexanderroidl](https://github.com/alexanderroidl))\n\n## Changelog for v3\n\n- Each tmdb function has the correct parameter and response types based on the documentation\n- `append_to_response` should be added to the request parameter of the appropriate functions and not on the options\n- The last parameter to each function can be an axios config object and will overwrite anything on the underlying request.\n- Several functions have been renamed.\n- Search functions accept a string and will be used for the `query` property.\n\n## Changelog for v2\n\n- Source has been ported to TypeScript.\n- [Rate limiting was removed by tmdb](https://github.com/grantholle/moviedb-promise/issues/23). The functionality had remained, but has since been removed in v2. If you wish to add it back, you're welcome to open a PR to discuss its need.\n- The `MovieDb` class has been moved to be a property of the package export. You will need to reference the `MovieDb` property of the export in order to instantiate the class. See usage below for an example.\n- The constructor has been changed to accept only two parameters: an api key and the base url for tmdb.\n- The `session()` function has been renamed to `retrieveSession()`\n- Requests were previously made using [superagent](https://www.npmjs.com/package/superagent) as it was used by the [original `moviedb` package](https://github.com/impronunciable/moviedb). It has been replaced with [axios](https://www.npmjs.com/package/axios) now.\n\n## Integrations\n\n- [Gatsby source](https://github.com/LekoArts/gatsby-source-tmdb)\n\n## Installation\n\n```bash\nnpm install moviedb-promise --save\n```\n\n## Usage\n\nRequire the module and instantiate the class with your themoviedb.org api key.\n\n```js\nconst { MovieDb } = require('moviedb-promise')\nconst moviedb = new MovieDb('your api key')\n```\n\n### `async/await` reminder\n\nAll functions return a Promise, which means that you can also use `async/await`. The caveat of using `await` when making function calls is that the `await` has to be within a function that has been declared `async`. Keep that in mind if you plan to use `await`.\n\n## Examples\n\n```js\n// Using just the Promise\nmoviedb\n  .searchMovie({ query: 'Alien' })\n  .then((res) =\u003e {\n    console.log(res)\n  })\n  .catch(console.error)\n\n// Using await\n// You probably wouldn't ever use it this way...\n;(async function () {\n  try {\n    const res = await moviedb.searchMovie({ query: 'alien' })\n    console.log(res)\n  } catch (e) {\n    console.log(e)\n  }\n})()\n\n// This is a more reasonable example\nconst findMovie = async (title) =\u003e {\n  // Equivalant to { query: title }\n  const res = await moviedb.searchMovie(title)\n\n  return res\n}\n\ntry {\n  const results = findMovie('alien')\n} catch (e) {\n  // Do something\n}\n```\n\nor\n\n```js\nmoviedb\n  .movieInfo({ id: 666 })\n  .then((res) =\u003e {\n    console.log(res)\n  })\n  .catch(console.error)\n```\n\nor\n\ncontroller file example that\n\n- uses async await\n- reads from a .env file\n- includes parameters\n- handles errors\n\n```js\nimport { MovieDb } from 'moviedb-promise'\nimport dotenv from 'dotenv'\n\ndotenv.config()\n\nconst moviedb = new MovieDb(process.env.KEY)\n\nconst newError = (name) =\u003e {\n  const e = new Error(name)\n  e.name = name\n  return Promise.reject(e)\n}\n\nexport const searchMovie = async (req) =\u003e {\n  const parameters = {\n    query: req.query.name,\n    page: req.query.page,\n  }\n  try {\n    const res = await moviedb.searchMovie(parameters)\n    return res.results\n  } catch (error) {\n    return newError(error)\n  }\n}\n\nexport const searchPerson = async (req) =\u003e {\n  const parameters = {\n    query: req.query.name,\n    page: 1,\n  }\n  try {\n    const res = await moviedb.searchPerson(parameters)\n    return res.results\n  } catch (error) {\n    return newError(error)\n  }\n}\n\nexport const movieKeywords = async (req) =\u003e {\n  try {\n    const res = await moviedb.movieKeywords({ query: req.query.name })\n    return res.results\n  } catch (error) {\n    return newError(error)\n  }\n}\n```\n\nSome endpoints, such as watchlist endpoints, have an optional account id parameter. If you have a [session id](https://developers.themoviedb.org/3/authentication/how-do-i-generate-a-session-id), you don't need to provide that parameter.\n\n```js\n// This is the same as calling it as\n// moviedb.accountMovieWatchlist({ id: '{account_id}' })\nmoviedb.sessionId = 'my-cached-session-id'\nmoviedb\n  .accountMovieWatchlist()\n  .then((res) =\u003e {\n    // Your watchlist items\n    console.log(res)\n  })\n  .catch(console.error)\n\n// Creating a session id would look something like this\nmoviedb\n  .requestToken()\n  .then((token) =\u003e {\n    // Now you need to visit this url to authorize\n    const tokenUrl = `https://www.themoviedb.org/authenticate/${token}`\n  })\n  .catch(console.error)\n\n// After that has been authorized, you can get the session id\nmoviedb\n  .retrieveSession()\n  .then((sessionId) =\u003e {\n    // Probably cache this id somewhere to avoid this workflow\n    console.log(sessionId)\n\n    // After the sessionId is cached, the next time use instantiate the class,\n    // set the sessionId by moviedb.sessionId = 'my-session-id'\n\n    // This can be called now because sessionId is set\n    moviedb\n      .accountMovieWatchlist()\n      .then((res) =\u003e {\n        // Your watchlist items\n        console.log(res)\n      })\n      .catch(console.error)\n  })\n  .catch(console.error)\n```\n\n## Available methods\n\nThe Function column lists all the available functions in the class. The Endpoint column lists possible request parameters (placeholders prefixed with `:`) needed for the call. If the endpoint doesn't have any placeholders, check out the [documentation](https://developers.themoviedb.org/3/) for the query parameters you can use.\n\n### Examples\n\n| Function | Endpoint |\n| -------- | -------- |\n| tvInfo   | tv/:id   |\n\n```js\n// Two ways:\n// The object key matches the placeholder name\nmoviedb.tvInfo({ id: 61888 }).then(...)\n\n// Or for simplicity, if it only has one placeholder\nmoviedb.tvInfo(61888).then(...)\n```\n\n| Function    | Endpoint     |\n| ----------- | ------------ |\n| searchMovie | search/movie |\n\nThere aren't any placeholders, but the [documentation](https://developers.themoviedb.org/3/search/search-movies) shows there are `language`, `query`, `page`, `include_adult`, `region`, `year`, and `primary_release_year` available to use. Each expects a certain data type or format, so check out the docs for the details.\n\n```js\nconst parameters = {\n  query: 'Kindergarten Cop',\n  language: 'fr' // ISO 639-1 code\n}\n\nmoviedb.searchMovie(parameters).then(...)\n```\n\n### Complete function list\n\n| Function                 |\n| ------------------------ |\n| configuration            |\n| countries                |\n| jobs                     |\n| languages                |\n| primaryTranslations      |\n| timezones                |\n| find                     |\n| searchCompany            |\n| searchCollection         |\n| searchKeyword            |\n| searchMovie              |\n| searchMulti              |\n| searchPerson             |\n| searchTv                 |\n| searchList               |\n| collectionInfo           |\n| collectionImages         |\n| collectionTranslations   |\n| discoverMovie            |\n| discoverTv               |\n| trending                 |\n| movieInfo                |\n| movieAccountStates       |\n| movieAlternativeTitles   |\n| movieChanges             |\n| movieCredits             |\n| movieExternalIds         |\n| movieImages              |\n| movieKeywords            |\n| movieReleaseDates        |\n| movieVideos              |\n| movieWatchProvidersForId |\n| movieWatchProviders      |\n| movieTranslations        |\n| movieRecommendations     |\n| movieSimilar             |\n| movieReviews             |\n| movieLists               |\n| movieRatingUpdate        |\n| movieRatingDelete        |\n| movieLatest              |\n| movieNowPlaying          |\n| moviePopular             |\n| movieTopRated            |\n| upcomingMovies           |\n| tvInfo                   |\n| tvAccountStates          |\n| tvAlternativeTitles      |\n| tvChanges                |\n| tvContentRatings         |\n| tvCredits                |\n| episodeGroups            |\n| tvExternalIds            |\n| tvImages                 |\n| tvKeywords               |\n| tvRecommendations        |\n| tvReviews                |\n| tvScreenedTheatrically   |\n| tvSimilar                |\n| tvTranslations           |\n| tvVideos                 |\n| tvWatchProvidersForId    |\n| tvWatchProviders         |\n| tvRatingUpdate           |\n| tvRatingDelete           |\n| tvLatest                 |\n| tvAiringToday            |\n| tvOnTheAir               |\n| tvPopular                |\n| tvTopRated               |\n| seasonInfo               |\n| seasonChanges            |\n| seasonAccountStates      |\n| seasonCredits            |\n| seasonExternalIds        |\n| seasonImages             |\n| seasonVideos             |\n| episodeInfo              |\n| episodeChanges           |\n| episodeAccountStates     |\n| episodeCredits           |\n| episodeExternalIds       |\n| episodeImages            |\n| episodeTranslations      |\n| episodeRatingUpdate      |\n| episodeRatingDelete      |\n| episodeVideos            |\n| personInfo               |\n| personChanges            |\n| personMovieCredits       |\n| personTvCredits          |\n| personCombinedCredits    |\n| personExternalIds        |\n| personImages             |\n| personTaggedImages       |\n| personTranslations       |\n| personLatest             |\n| personPopular            |\n| creditInfo               |\n| listInfo                 |\n| listStatus               |\n| createList               |\n| createListItem           |\n| removeListItem           |\n| clearList                |\n| deleteList               |\n| genreMovieList           |\n| genreTvList              |\n| keywordInfo              |\n| keywordMovies            |\n| companyInfo              |\n| companyAlternativeNames  |\n| companyImages            |\n| accountInfo              |\n| accountLists             |\n| accountFavoriteMovies    |\n| accountFavoriteTv        |\n| accountFavoriteUpdate    |\n| accountRatedMovies       |\n| accountRatedTv           |\n| accountRatedTvEpisodes   |\n| accountMovieWatchlist    |\n| accountTvWatchlist       |\n| accountWatchlistUpdate   |\n| changedMovies            |\n| changedTvs               |\n| changedPeople            |\n| movieCertifications      |\n| tvCertifications         |\n| networkInfo              |\n| networkAlternativeNames  |\n| networkImages            |\n| review                   |\n| episodeGroup             |\n\n## Support for append_to_response\n\nThe movieInfo, tvInfo, seasonInfo, episodeInfo and personInfo methods support an option to specify the [TMDB API's append_to_response query parameter](https://developers.themoviedb.org/3/getting-started/append-to-response). This makes it possible to make sub requests within the same namespace in a single HTTP request. Each request will get appended to the response as a new JSON object.\n\nIn order to receive type support for the items returned with an `append_to_response` request, you'll need to cast the attributes as their appropriate type. **Note** this requires you to be using TypeScript.\n\n```ts\nconst response = await moviedb.movieInfo({ id: tmdbId, append_to_response: \"release_dates\" })\n  as MovieResponse \u0026 { release_dates: MovieReleaseDatesResponse }\n```\n\nIn this case, `response.release_dates` will be cast as `MovieReleaseDatesResponse` since it's not in the default `MovieResponse` that gets returned with `movieInfo()`.\n\n```js\nconst res = await api.tvInfo({\n  id: 4629,\n  append_to_response: 'season/1,season/1/credits',\n})\n```\n\n### Request Options\n\nThe last parameter of the endpoint function calls is an [axios request config object](https://github.com/axios/axios#request-config). Those settings will overwrite anything on the underlying request.\n\n```js\n// Add a timeout restriction to the request\nconst res = await api.tvInfo(4629, { timeout: 10000 })\n```\n\nor when combining multiple options append_to_response is desired:\n\n```js\nconst res = await api.tvInfo(\n  {\n    id: 4629,\n    append_to_response: 'season/1,season/1/credits',\n  },\n  {\n    timeout: 10000,\n  },\n)\n```\n\n## Contributing\n\nFirst, thanks for taking the time!\n\n#### Testing\n\n- Before submitting a pull request, please run `npm run test`\n- Make sure all tests pass before submitting a pull request\n- Add tests from any features you add\n\n#### Submitting changes\n\nPlease submit a pull request with an outline of what you've added/changed/removed. When you submit your code, please include examples and make sure that you submit one feature per commit.\n\n#### Syntax guidelines\n\n- Use TypeScript\n- Run `npm run format` before submitting to let Prettier handle the formatting\n- Avoid code that is platform dependent\n\n#### Documentation guidelines\n\n- Use Markdown\n- Reference a class with [ClassName]\n- Reference an instance of a class with [Classname::methodName]\n- Reference a method in class with [Classname.methodName]\n\n## License\n\n[MIT](LICENSE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrantholle%2Fmoviedb-promise","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrantholle%2Fmoviedb-promise","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrantholle%2Fmoviedb-promise/lists"}