Python Library: tmdbv3api | fetching movie data

Python wrapper for the TMDB API -

17 Jul 2022 starting note *note date indicates latest update.

Library resources
PyPI ---
Github ---
API Documentation
Wrapper Documentation

Using this library to fetch data from TMDB:
The Movie Database (TMDB) is a popular, user editable database for movies and TV shows.

Movie endpoint

Search by Movie ID:


Generic Search example

.search using movie title.

movie = Movie()
search ='Interstellar') # list of dict
for result in search:


{'adult': False, 'backdrop_path': '/pbrkL804c8yAv3zBZR4QPEafpAR.jpg', 'genre_ids': [12, 18, 878], 'id': 157336, 'original_language': 'en', 'original_title': 'Interstellar', 'overview': 'The adventures of a group of explorers who make use of a newly discovered wormhole to surpass the limitations on human space travel and conquer the vast distances involved in an interstellar voyage.', 'popularity': 189.43, 'poster_path': '/gEU2QniE6E77NI6lCU6MxlNBvIx.jpg', 'release_date': '2014-11-05', 'title': 'Interstellar', 'video': False, 'vote_average': 8.4, 'vote_count': 28848}
{'adult': False, 'backdrop_path': '/qpynYr3NPHkj1E7UKfd0OWJ2e2n.jpg', 'genre_ids': [99], 'id': 301959, 'original_language': 'en', 'original_title': "Interstellar: Nolan's Odyssey", 'overview': "A look behind the lens of Christopher Nolan's space epic.", 'popularity': 14.741, 'poster_path': '/wUmyEjrLqYpJYjVMD2YR7IffFeE.jpg', 'release_date': '2014-11-05', 'title': "Interstellar: Nolan's Odyssey", 'video': False, 'vote_average': 7.7, 'vote_count': 158}
{'adult': False, 'backdrop_path': '/zjZmXyugypJ8aDc2WdybuG9cmoh.jpg', 'genre_ids': [99], 'id': 336592, 'original_language': 'en', 'original_title': 'The Science of Interstellar', 'overview': "Matthew McConaughey narrates a fascinating look at Christopher Nolan's sci-fi film Interstellar, including scientific foundations, the work of consulting Scientist Kip Thorne, basic film themes, the science behind the search for planets capable of hosting life, space-time and the theory of relativity, the science of wormholes and black holes, crafting the film's visuals based on real scientific observation, the birth of the universe, the Dust Bowl and the evolution of dust as a toxin, the likelihood of future dust storms, the prospects of escaping a dying or doomed planet, and the possibilities of colonizing Mars.", 'popularity': 9.55, 'poster_path': '/qUZiVjFBd67WKktIrjJ9H3tesyo.jpg', 'release_date': '2014-11-25', 'title': 'The Science of Interstellar', 'video': False, 'vote_average': 7, 'vote_count': 21}
{'adult': False, 'backdrop_path': '/wUZID3WzrzuIQmcIjXahZkV1ItI.jpg', 'genre_ids': [878], 'id': 398188, 'original_language': 'en', 'original_title': 'Interstellar Wars', 'overview': 'For Millennia the Aliien force has watched and waited, a brooding menace that has now at last decided to take over the Earth. Communications systems worldwide are sent into chaos by a strange atmospheric interference and this has turned into a global phenomenon. A massive spaceship headed towards Earth and smaller spaceships began to cover entire cities around the world. Suddenly, the wonder turns into horror as the spaceships destroy the cities with energy weapons. When the world counterattacks, the alien ships are invincible to military weapons.  The survivors have to use their wits to kill the aliens, or die.', 'popularity': 5.229, 'poster_path': '/4uWZ8cdrXMLiyLNgdmqQCIM6z40.jpg', 'release_date': '2016-06-09', 'title': 'Interstellar Wars', 'video': False, 'vote_average': 3.7, 'vote_count': 10}
{'adult': False, 'backdrop_path': None, 'genre_ids': [35], 'id': 287954, 'original_language': 'en', 'original_title': 'Lolita from Interstellar Space', 'overview': 'An undeniably beautiful alien is sent to Earth to study the complex mating rituals of human beings, which leads to the young interstellar traveler experiencing the passion that surrounds the centuries-old ritual of the species.', 'popularity': 6.842, 'poster_path': '/nhWlip1s5YzhRFKGlHABGJrBhZn.jpg', 'release_date': '2014-03-08', 'title': 'Lolita from Interstellar Space', 'video': False, 'vote_average': 5.7, 'vote_count': 6}
{'adult': False, 'backdrop_path': None, 'genre_ids': [99], 'id': 529107, 'original_language': 'en', 'original_title': 'Inside Interstellar', 'overview': "Cast and crew of Christopher Nolan's 'Interstellar' discuss project origins, the film's imagery, ambitions, incorporating IMAX footage, the human element within the film, arm shooting locations outside of Calgary, the set construction and design, working with real corn, mechanical characters, including backstory, design, the blend of practical and digital effects in bringing them to life, the differences in the characters, the human performances behind the characters, the creative process behind the film's music, Icelandic locations, vehicle interiors, the processes of simulating the absence of gravity, the crucial end-film visuals and influence and inspiration for future generations", 'popularity': 3.894, 'poster_path': '/vemBplPKQhVe5cRWL7kxtgp15Vq.jpg', 'release_date': '2015-03-31', 'title': 'Inside Interstellar', 'video': False, 'vote_average': 6.6, 'vote_count': 8}
{'adult': False, 'backdrop_path': '/lQS9il7YqGjmmBefZY27uG5wbzT.jpg', 'genre_ids': [99], 'id': 660698, 'original_language': 'en', 'original_title': 'Faster Than Light: the Dream of Interstellar Flight', 'overview': '“Faster Than Light” explores the longstanding quest to develop spacecraft with enough power and speed to reach the stars. The film asks: What will it take to reach a newly discovered planet circling our Sun’s nearest neighbor, Proxima Centauri? Based on real science and engineering, “Faster Than Light” takes audiences on a thrilling journey into the future, aboard laser-driven space sails, antimatter engines, and even warp drive – right out of science fiction. “Who can say how far, and how fast, our technology will one day take us?” said director Thomas Lucas.', 'popularity': 10.358, 'poster_path': '/mbgJxB70uMFK2H8DXHUj5lAMgXx.jpg', 'release_date': '2017-06-07', 'title': 'Faster Than Light: the Dream of Interstellar Flight', 'video': False, 'vote_average': 6, 'vote_count': 1}
{'adult': False, 'backdrop_path': None, 'genre_ids': [], 'id': 838389, 'original_language': 'en', 'original_title': "Interstellar: Desgornia's Cut", 'overview': "A team of explorers travel through a wormhole in space in an attempt to ensure humanity's survival.", 'popularity': 2.571, 'poster_path': '/geOB25wA6VHSlANpJ1UMyuokjJl.jpg', 'release_date': '', 'title': "Interstellar: Desgornia's Cut", 'video': False, 'vote_average': 0, 'vote_count': 0}
{'adult': False, 'backdrop_path': None, 'genre_ids': [28, 14, 878], 'id': 460616, 'original_language': 'en', 'original_title': 'Interstellar Civil War: Shadows of the Empire', 'overview': "The Imperial Empire is attacked by an Alliance of rebels led by fanatical mystics. The ruler, Empress Nobu, the 8th generation of her family, wants to execute a bold plan to rescue a cyborg, Leah C6, trapped on the battle ravaged planet Endor. The Empress believes Leah C6 holds the secret to destroying the Alliance of Rebels before their insurgency can kill millions of citizens of the Empire. She recruits her heroic fleet commander, Lord General Luka Raan and asks him to gather a team from the Empire's elite soldiers, the Galactic Rangers. Raan assembles the team in the ruins of Endor which was attacked by depraved Rebels and outlaws led by, Kindo-Ker, a fanatical mystic in Dark Energy. The Galactic Rangers begin a desperate search to find and rescue Leah C6 before the Alliance Rebels can.", 'popularity': 1.457, 'poster_path': '/1lDY7ZpEKOl3OaIQURjRbmFPfT8.jpg', 'release_date': '2018-04-15', 'title': 'Interstellar Civil War: Shadows of the Empire', 'video': False, 'vote_average': 4, 'vote_count': 1}
{'adult': False, 'backdrop_path': None, 'genre_ids': [12], 'id': 552531, 'original_language': 'en', 'original_title': "The Prom Goer's Interstellar Excursion", 'overview': 'High schooler Bennett lands the prom date of his dreams, Sophie, just days before the dance. Not long after, he witnesses Sophie being abducted by aliens in the middle of the New Mexico desert.', 'popularity': 0.6, 'poster_path': None, 'release_date': '', 'title': "The Prom Goer's Interstellar Excursion", 'video': False, 'vote_average': 0, 'vote_count': 0}
{'adult': False, 'backdrop_path': None, 'genre_ids': [], 'id': 763179, 'original_language': 'en', 'original_title': 'Cosmic Journey: The Voyager Interstellar Mission and Message', 'overview': 'The farthest Voyager: "Cosmic Journey," a documentary premiering on the A&E cable network, tells the saga of the farthest-flung space journey to date - the Voyager interstellar mission, which started out 25 years ago and sailed past Jupiter, Saturn, Uranus and Neptune in the 1980s.', 'popularity': 1.091, 'poster_path': None, 'release_date': '2003-01-16', 'title': 'Cosmic Journey: The Voyager Interstellar Mission and Message', 'video': False, 'vote_average': 0, 'vote_count': 0}
{'adult': False, 'backdrop_path': None, 'genre_ids': [35, 18], 'id': 716603, 'original_language': 'en', 'original_title': 'Only Interstellar Pinball Lives Forever', 'overview': "A young boy (played by an actual re-purposed Sunday school puppet) loses all faith in religion and afterlife options after having to bury his umpteenth pet, and vows that someday, when he's an adult with money, he'll find a way to become an 'eternal molecule' through science. Then, twenty-two years later, the playing of a pinball game brings dredges up the memory of that vow. Utilizing the hallucinogenic properties of alcohol and cough syrup blends, he undertakes the design of a pinball machine so poignant and dignified that it will convince scientists to create a pinball that we can download our consciousness into and thereby become digitally immortal.", 'popularity': 0.6, 'poster_path': '/uLJMGZlrkmvAO9Ria9zrp8GUqjx.jpg', 'release_date': '2010-06-28', 'title': 'Only Interstellar Pinball Lives Forever', 'video': False, 'vote_average': 0, 'vote_count': 0}
{'adult': False, 'backdrop_path': '/jiD3YVlYyOqcIgLXGn1W7r0rL7p.jpg', 'genre_ids': [16, 878, 10402, 12], 'id': 11049, 'original_language': 'ja', 'original_title': 'Interstella 5555: The 5tory of the 5ecret 5tar 5ystem', 'overview': 'Four talented alien musicians are kidnapped by a record producer who disguises them as humans. Shep, a space pilot in love with bass player Stella, follows them to Earth. Reprogrammed to forget their real identities and renamed The Crescendolls, the group quickly becomes a huge success playing soulless corporate pop. At a concert, Shep manages to free all the musicians except Stella, and the band sets out to rediscover who they really are -- and to rescue Stella.', 'popularity': 9.073, 'poster_path': '/AsvPgdcSlHocAbMp3yGZXjPiKKF.jpg', 'release_date': '2003-05-28', 'title': 'Interstella 5555: The 5tory of the 5ecret 5tar 5ystem', 'video': False, 'vote_average': 7.8, 'vote_count': 323}
{'adult': False, 'backdrop_path': None, 'genre_ids': [], 'id': 986255, 'original_language': 'en', 'original_title': 'How to Colonize the Stars: The Challenge of Interstellar Flight', 'overview': "Leading physicists and engineers in the field of interstellar travel discuss some of the deep issues we face when considering the problem of sending spacecraft to other stars. Will mankind ever truly become a space fairing civilization? Space colonization is no longer the fodder of science fiction, it is becoming a reality. We'll need to learn how to grow food, manufacture and live off our planet.", 'popularity': 0.6, 'poster_path': '/ddYoMPJioxY7qQxt7JyUaLCWMjw.jpg', 'release_date': '2009-06-09', 'title': 'How to Colonize the Stars: The Challenge of Interstellar Flight', 'video': False, 'vote_average': 0, 'vote_count': 0}
{'adult': False, 'backdrop_path': None, 'genre_ids': [28], 'id': 649745, 'original_language': 'zh', 'original_title': '星际流浪', 'overview': 'The film tells that the catastrophe era, the earth is a waste land, the survivors are divided into wanderers and civilians, they are attached to the rule of the interstellar armed groups, in which the rogues rely on the plundering of civilian materials as a livelihood, making civilians in this harsh It is difficult to survive in the environment. After a hundred years of black technology explosion, it will bring about a civilized renaissance. In the face of the deteriorating planet, mankind is determined to continue the race and is determined to interstellar immigration. The "curvature engine" developed by the Chinese researcher Hailei has become the key to the interstellar immigration, and is also the target of robbers and interstellar armed groups.', 'popularity': 0.664, 'poster_path': '/oUWDbde5bWu9syBZglWDIwB1SPm.jpg', 'release_date': '2019-08-02', 'title': 'Interstellar Wandering', 'video': False, 'vote_average': 0, 'vote_count': 0}
{'adult': False, 'backdrop_path': '/yl9QqtS3tbLCL4e6lHM349joALK.jpg', 'genre_ids': [28, 53, 878], 'id': 47663, 'original_language': 'en', 'original_title': 'Trancers 5: Sudden Deth', 'overview': "Jack Deth is back for one more round with the trancers. Jack must attempt to find his way home from the other-dimensional world of Orpheus, where magic works and the trancers were the ruling class (before Trancers IV, that is). Unfortunately, Jack's quest to find the mystical Tiamond in the Castle of Unrelenting Terror may be thwarted by the return of Caliban, king of the trancers who was thought dead.", 'popularity': 3.503, 'poster_path': '/t4to2HtWP1lT6TkvTwSUD7cQqIH.jpg', 'release_date': '1994-11-04', 'title': 'Trancers 5: Sudden Deth', 'video': False, 'vote_average': 4.9, 'vote_count': 14}
{'adult': False, 'backdrop_path': None, 'genre_ids': [], 'id': 772265, 'original_language': 'zh', 'original_title': '星际变种', 'overview': 'After long years of searching, the unknown creature was finally captured by the crew of the Thunder and named "Baal". Under the lure of Baal, the young Jamie released it. "Baal" who escaped from the experimental tank killed all the crew and Jamie\'s parents, and the young Jamie escaped back to Earth in an escape capsule alone. Twenty years later, a variant of "Baal" appeared on the earth, and Jamie began the story of the journey to save mankind and self-redemption', 'popularity': 0.6, 'poster_path': '/mMidfcVVaESbYdF9Tzgejp3FvPR.jpg', 'release_date': '', 'title': 'Variant', 'video': False, 'vote_average': 0, 'vote_count': 0}
{'adult': False, 'backdrop_path': None, 'genre_ids': [878], 'id': 261443, 'original_language': 'en', 'original_title': 'Angry Planet', 'overview': 'A criminal sentenced to life on a prison planet reveals his true purpose: to extract revenge on the killers who murdered his family.', 'popularity': 0.995, 'poster_path': '/6Bv0rl9R5gaN8X58LOjUT4MWKR7.jpg', 'release_date': '2008-01-01', 'title': 'Angry Planet', 'video': False, 'vote_average': 2.8, 'vote_count': 2}
{'adult': False, 'backdrop_path': '/aPXNyG6035Wz2DhtGAgf7PeGNsz.jpg', 'genre_ids': [878, 28], 'id': 47662, 'original_language': 'en', 'original_title': 'Trancers 4: Jack of Swords', 'overview': 'Jack is now back in the future. He had since lost Lena, and finds out that he\'s lost his other wife Alice to none other than Harris. While heading out for another assignment, something goes awry with the TCL chamber. Jack finds himself in a whole new dimension. He also runs across a different version of trancers. These guys seem to be in control of this planet. Jack manages to assist a rebel group known as the "Tunnel Rats" crush the rule of the evil Lord Calaban.', 'popularity': 2.457, 'poster_path': '/ec081IWKkRalPO14KAmqJ2vWeYB.jpg', 'release_date': '1994-02-02', 'title': 'Trancers 4: Jack of Swords', 'video': False, 'vote_average': 5.4, 'vote_count': 21}
{'adult': False, 'backdrop_path': '/ynF37QsffZ1b3Xm2ktpb79ioP6R.jpg', 'genre_ids': [99], 'id': 436305, 'original_language': 'en', 'original_title': 'The Farthest', 'overview': "The captivating tales of the people and events behind one of humanity's greatest achievements in exploration: NASA's Voyager mission.", 'popularity': 3.57, 'poster_path': '/jHbSJo4FoKvqaGn3b7q49bcSYVZ.jpg', 'release_date': '2018-03-15', 'title': 'The Farthest', 'video': False, 'vote_average': 7.8, 'vote_count': 41}

Person endpoint

.details using Person ID


person = Person()
p = person.details(138) # 138 is Quentin Tarantino's ID on TMDB

returns:'Quentin Tarantino'
p.biography="Quentin Jerome Tarantino (born March 27, 1963) is an American film director, screenwriter, producer, cinematographer and actor. In the early 1990s he was an independent filmmaker whose films used nonlinear storylines and aestheticization of violence. His films have earned him a variety of Academy Award, Golden Globe, BAFTA and Palme d'Or Awards and he has been nominated for Emmy and Grammy Awards. In 2007, Total Film named him the 12th-greatest director of all time.\n\nTarantino was born in Knoxville, Tennessee, the son of Connie McHugh Tarantino Zastoupil, a health care executive and nurse born in Knoxville, and Tony Tarantino, an actor and amateur musician born in Queens, New York. Tarantino's mother allowed him to quit school at age 17, to attend an acting class full time. Tarantino gave up acting while attending the acting school, saying that he admired directors more than actors. Tarantino also worked in a video rental store before becoming a filmmaker, paid close attention to the types of films people liked to rent, and has cited that experience as inspiration for his directorial career.\n\nDescription above from the Wikipedia article Quentin Tarantino, licensed under CC-BY-SA, full list of contributors on Wikipedia."

.movie_credits using Person ID


person = Person()
p = person.movie_credits(138) # <class 'tmdbv3api.as_obj.AsObj'> with 3 values: cast, crew and id. Note: 138 is Quentin Tarantino
print("All movies where that person is listed as CAST:")
for x in p.cast:
print("\nAll movies where that person is listed as CREW:")
for y in p.crew:

returns (edited to 2 results for length):

All movies where that person is listed as CAST:
{'adult': False, 'backdrop_path': '/olFse9isSpx1L2i2wKNFJO9OR83.jpg', 'genre_ids': [35], 'id': 10614, 'original_language': 'en', 'original_title': "My Best Friend's Birthday", 'overview': "My Best Friend's Birthday is a partially lost black-and-white amateur film. The original cut was about 70 minutes long but due to a fire only 36 minutes of the film survived. It is about Mickey, who has been dumped by his girlfriend, and Clarence, who's trying to give his friend an unforgettable birthday.", 'popularity': 6.475, 'poster_path': '/q5tp3fPHL3jveTjREC4WieY7AoU.jpg', 'release_date': '1987-01-01', 'title': "My Best Friend's Birthday", 'video': False, 'vote_average': 5.583, 'vote_count': 103, 'character': 'Clarence Pool', 'credit_id': '52fe43949251416c75015ecb', 'order': 0}
{'adult': False, 'backdrop_path': '/ulKw0ytuwp9L2RmikvO3mg8Ll6b.jpg', 'genre_ids': [99], 'id': 631143, 'original_language': 'en', 'original_title': 'QT8: The First Eight', 'overview': 'A detailed account of the life and artistic career of legendary filmmaker Quentin Tarantino, from his early days as a video club manager to the scandalous fall in disgrace of producer Harvey Weinstein. A story about how to shoot eight great movies and become an icon of modern pop culture.', 'popularity': 10.886, 'poster_path': '/rGPwMYUeygsUAmo0NS8IPlhQEfH.jpg', 'release_date': '2019-10-21', 'title': 'QT8: The First Eight', 'video': False, 'vote_average': 7.3, 'vote_count': 105, 'character': 'Self', 'credit_id': '60d4f3cd3e6f2b00298aa267', 'order': 0}

All movies where that person is listed as CREW:
{'adult': False, 'backdrop_path': None, 'genre_ids': [878], 'id': 755563, 'original_language': 'pt', 'original_title': 'Um Moço Muito Branco', 'overview': '', 'popularity': 0.6, 'poster_path': '/wwzfIItcHRKeftnCqRPkV42BphE.jpg', 'release_date': '2019-02-06', 'title': 'Um Moço Muito Branco', 'video': False, 'vote_average': 0.0, 'vote_count': 0, 'credit_id': '5f8f217d55c1f400361e6dd1', 'department': 'Art', 'job': 'Second Assistant Art Director'}
{'adult': False, 'backdrop_path': '/c7k9ZZb1MoFzJeyjphKRMLHOgqU.jpg', 'genre_ids': [28, 53], 'id': 1991, 'original_language': 'en', 'original_title': 'Death Proof', 'overview': "Austin's hottest DJ, Jungle Julia, sets out into the night to unwind with her two friends Shanna and Arlene. Covertly tracking their moves is Stuntman Mike, a scarred rebel leering from behind the wheel of his muscle car, revving just feet away.", 'popularity': 19.585, 'poster_path': '/vtu6H4NWnQVqEp3aanUq3hNeeot.jpg', 'release_date': '2007-05-22', 'title': 'Death Proof', 'video': False, 'vote_average': 6.817, 'vote_count': 4159, 'credit_id': '52fe4329c3a36847f803f099', 'department': 'Camera', 'job': 'Director of Photography'}

My functions

For finding the director(s) based on Movie ID:

def director_by_movie_id(movie_id): # returns list of strings
    list_directors = []
    movie = Movie()
    movie_title = movie.details(movie_id)['title']
    m = movie.credits(movie_id) 
    for crew in m.crew: # list of dict
        if crew['job'] == 'Director':
    print(f"Checked {movie_title}: {' '.join(list_directors)}")
    return list_directors

For getting all movies from a specific director based on the Person ID:

def movies_from_director(director_id): # returns list of movie IDs
    person = Person()
    movie = Movie()
    list_movies = []
    list_movies_ids_from_director = []
    list_movies_from_director = []
    director_name = person.details(director_id)['name']
    p = person.movie_credits(director_id)

    print(f"Checking {len(p.crew)} movies where {director_name} is listed as crew:")
    for movie in p.crew: # all movies where person is listed in crew
        movie_title = movie['title']
        movie_id = movie['id']
        if movie_id not in list_movies: # dedupe
            list_movies.append(movie_id) # dedupe
            directors = director_by_movie_id(movie_id) # returns list of directors, usually only one
            if director_name in directors:
                # print(movie_title)
    print(f"\n\nFrom {director_name} ({len(list_movies_from_director)} movies):")
    for movie_found in list_movies_from_director:
    return list_movies_ids_from_director

Getting list of top rated movies

This works, but returns only 20 movies:

movie = Movie()
popular = movie.top_rated()

for p in popular:

It seems this might be a limitation of the API v3, with v4 solving this:

What are some of the improvements in v4?
You can import "unlimited" items in a single request
You can use mixed type (movie and TV) lists
You can use private lists
You can add and use comments per item
There are more sort options
They are faster

Though the wrapper is called tmdbv3api so does not support v4.
Might need to scrap the library and do manual requests instead. It's a pain - I always struggle with authentication.

The quest continues at Nic Note: Library: tmdbapis | fetching movie data...