Package: mapi
mapimapi (MetadataAPI) is a python library which provides a high-level interface for media database providers, allowing users to efficiently search for television and movie metadata using a simple interface.Installation$ pip install mapiRunning Tests$ pip install -r requirements-testing.txt$ python -m pytestNotes:Runpip install -r requirements-dev.txtfirst to install testing dependenciesTesting requires internet accessTesting requiresAPI_KEY_TMDBandTVDB_API_KEYto be defined as environment variablesExamplesSearching for a television show by series using TVDbHere is a fairly straight forward example, say we just want to get a listing of episodes from Rick and Morty season 2:frommapi.providersimportTVDbclient=TVDb()# API Key taken from environment variablesresults=client.search(series='Rick and Morty',season=2)forresultinresults:print(result)Rick and Morty - 02x01 - A Rickle in Time
Rick and Morty - 02x02 - Mortynight Run
Rick and Morty - 02x03 - Auto Erotic Assimilation
Rick and Morty - 02x04 - Total Rickall
Rick and Morty - 02x05 - Get Schwifty
Rick and Morty - 02x06 - The Ricks Must Be Crazy
Rick and Morty - 02x07 - Big Trouble in Little Sanchez
Rick and Morty - 02x08 - Interdimensional Cable 2: Tempting Fate
Rick and Morty - 02x09 - Look Who's Purging Now
Rick and Morty - 02x10 - The Wedding SquanchersSearching for a movie by title and yearOkay, so no we want to look up some movies. We can search for using a specific year, by an upper range using'-year', by a lower range using'year-', or between a range of years using'year-year'. Lets use the latter to get a listing of Star Trek movies from the 90s. As it turns out, there's a lot.frommapi.providersimportTMDbclient=TMDb()results=client.search(title='Star Trek',year='1990-1999')fori,resultinenumerate(results,1):print('%d)%s'%(i,result))ifi>9:break1) Star Trek: Voyager (1995)
2) Star Trek: First Contact (1996)
3) Star Trek VI: The Undiscovered Country (1991)
4) Star Trek: Generations (1994)
5) Star Trek: Insurrection (1998)
6) Star Trek: The Experience - The Klingon Encounter (1998)
7) Journey's End: The Saga of Star Trek - The Next Generation (1994)
8) Star Trek: 30 Years and Beyond (1996)
9) Ultimate Trek: Star Trek's Greatest Moments (1999)
10) Star Trek: A Captain's Log (1994)Searches return a generator, so by breaking on 10, we only ask for what we need, reducing the bandwidth and time required for the request.Looking up a movie by IDIf you just want to lookup metadata using an API Provider's ID code, you can do that too:frompprintimportpprintfrommapi.providersimportTMDbclient=TMDb()results=client.search(id_tmdb=9340)# Using TMDb IDpprint(dict(next(results))){'date': '1985-06-06',
 'id_tmdb': '9340',
 'media': 'movie',
 'synopsis': 'A young teenager named Mikey Walsh finds an old treasure map in '
             "his father's attic. Hoping to save their homes from demolition, "
             'Mikey and his friends Data Wang, Chunk Cohen, and Mouth '
             'Devereaux run off on a big quest to find the secret stash of '
             'Pirate One-Eyed Willie.',
 'title': 'The Goonies'}Some APIs, like TMDb, allow you to search by an IMDb'tt-const'as well:frompprintimportpprintfrommapi.providersimportTMDbclient=TMDb()results=client.search(id_imdb='tt0089218')# Using IMDb IDpprint(dict(next(results))){'date': '1985-06-06',
 'id_tmdb': 9340,
 'media': 'movie',
 'synopsis': 'A young teenager named Mikey Walsh finds an old treasure map in '
             "his father's attic. Hoping to save their homes from demolition, "
             'Mikey and his friends Data Wang, Chunk Cohen, and Mouth '
             'Devereaux run off on a big quest to find the secret stash of '
             'Pirate One-Eyed Willie.',
 'title': 'The Goonies'}Handling a search gone awryNot all searches yield results; maybe you had a typo, maybe the data just isn't there, either way there is no need to fret, this can be handled gracefully using exception handling:frommapi.exceptionsimportMapiNotFoundExceptionfrommapi.providersimportTMDbclient=TMDb()try:print(next(client.search(id_imdb='invalid_id')))exceptMapiNotFoundException:print('Nothing found :(')None found :(Usage DetailsProvider ConfigurationTVDb, TMDb, and OMDb require an API key to successfully be initialized.These can be provided using environment variables;API_KEY_TMDB,API_KEY_TVDB, andAPI_KEY_OMDBrespectively.These can also be provided asapi_key, a parameter to the provider classes.SearchingThe following table describes the permissible fields which may be used for a given search query. Extra fields are simply ignored.FieldAPITypeDescriptionNotesid_imdbTMDb, TVDb, OMDbstrIMDb movie id key1, 2id_tmdbTMDbstr / intTMDb movie id key2, 3id_tvdbTVDb series id keystr / intTVDb season id key2, 3titleTMDB, OMDbstrFeature's titleyearTMDB, OMDbstr / intFeature's release yeardateTVDBstrYYYY-MM-DD formatted4seriesTVDBstrSeries' nameseasonTVDBstr / intSeries' airing seasonepisodeTVDbstr / intSeries' airing episode3ResultsEach provider is guaranteed to return the following fields for a successful search as strings. Notice that they are largely the fields as the search parameters-- in fact, you can even next search calls within each other if you so desire.FieldAPIDescriptionid_tmdbTMDbTMDb movie id keyid_imdbOMDbIMDb movie id keyid_tvdbTVDbTVDb season id keydateALLMedia's release date (YYYY-MM-DD)synopsisALLMedia synopsismediaALLMedia type; eithermovieortelevisionseriesTVDbSeries' nameseasonTVDbSeries' airing seasonepisodeTVDBSeries' airing episodeFormattingMapi uses Python's standard string format conventions. You can call the builtinformat()function on a mapi object and use any of the results keys. You can use format specifiers on numeric fields like episodes and seasons. For instanceformat(metadata, "{series} S{season:02}E{episode:02}")would pad season and episode numbers to two digits.LicenseMIT. Seelicense.txtfor details.Notesid_imdb must be prefixed withtt.Although ID, title, and series are each optional, movie queries must have either an ID or title to yield any results, and television queries must have either and ID or series to yield any results.If this field is passed as a string it must be numeric.Dates may also be specified partially, i.e. asYYYY-MMorYYYY.