Skip to main content

An API for media database APIs which allows you to search for metadata using a simple, common interface

Project description

licence pypi travis_ci api


mapi (Metadata API) is a python library which provides a high-level interface for media database providers, allowing users to search for television and movie metadata using a simple interface. Supports and tested against Python 2.7, Python 3, and PyPy3.


Searching for a television show by series using TVDb

>>> from pprint import pprint
>>> from mapi.providers import TVDb
>>> client = TVDb(max_hits=3)
>>> hits ='Rick and Morty', season=2)
>>> pprint(hit)
[{'episode': '1',
  'id_tvdb': '275274',
  'media': 'television',
  'season': '2',
  'series': 'Rick and Morty',
  'synopsis': 'Rick, Morty, and Summer get into trouble when time is fractured '
              'by a feedback loop of uncertainty that split reality into more '
              'than one equally possible impossibilities. Meanwhile, Beth and '
              'Jerry go to extreme lengths to save a deer struck by their '
  'title': 'A Rickle in Time'},
 {'episode': '2',
  'id_tvdb': '275274',
  'media': 'television',
  'season': '2',
  'series': 'Rick and Morty',
  'synopsis': 'Rick teaches Morty to drive while leaving Jerry at a popular '
              "day care made just for him. Morty's conscience has him hunt "
              'down an assassin rather than spending the day at an alien '
  'title': 'Mortynight Run'},
 {'episode': '3',
  'id_tvdb': '275274',
  'media': 'television',
  'season': '2',
  'series': 'Rick and Morty',
  'synopsis': 'Rick gets emotionally invested when meeting an old friend, '
              'while Beth and Jerry have a falling out after making a '
              'discovery under the garage.',
  'title': 'Auto Erotic Assimilation'}]

Searching for a movie by title and year using IMDb

>>> from mapi.providers import IMDb
>>> client = IMDb(year_delta=1)
>>> hits ='The Goonies', year=1985)
>>> pprint(hits)
[{'id_imdb': 'tt0089218',
  'media': 'movie',
  'synopsis': 'In order to save their home from foreclosure, a group of '
              "misfits set out to find a pirate's ancient valuable treasure.",
  'title': 'The Goonies',
  'year': '1985'}]

Handling a search gone awry

>>> from mapi.providers import TMDb
>>> client = TMDb()
>>> try:
>>>     hits ='invalid_id')
>>> except MapiNotFoundException:
>>>     hits = 'None found :('
>>> print(hits)
None found :(



  • pip: pip install mapi
  • source: pip install .

Provider Configuration

Parameter Description Default Notes
api_key Developer API key None [1]
max_hits Restricts the maximum number of responses for a search 15  
year_delta Filters results around this value inclusively 5  


The following table describes the permissible fields which may be used for a given search query. Extra fields are simply ignored.

Field API Type Description Notes
id_imdb IMDb, TMDb, TVDb str IMDb movie id key [2] [3]
id_tmdb TMDb str / int TMDb movie id key [3] [4]
id_tvdb TVDb series id key str / int TVDb season id key [3] [4]
title IMDb, TMDb str Feature’s title  
year IMDb, TMDb str / int Feature’s release year  
series TVDb str Series’ name  
season TVDb str / int Series’ airing season  
episode TVDb str / int Series’ airing episode [4]


Each 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.

Field API Description
id_imdb IMDb IMDb movie id key
id_tmdb TMDb TMDb movie id key
id_tvdb TVDb TVDb season id key
title IMDb, TMDb Feature’s title
year IMDb, TMDb Feature’s release year
synopsis ALL Media synopsis
media ALL Media type; either ‘movie’ or ‘television’
series TVDb Series’ name
season TVDb Series’ airing season
episode TVDb Series’ airing episode


[1]required for TMDb and TVDb; alternatively, can be set by API_KEY_TMDB and API_KEY_TVDB enviroment variables, respectively
[2]id_imdb must be prefixed with ‘tt’.
[3](1, 2, 3) 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.
[4](1, 2, 3) If this field is passed as a string it must be numeric.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for mapi, version 1.0.3
Filename, size File type Python version Upload date Hashes
Filename, size mapi-1.0.3.tar.gz (13.2 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page