Link Search Menu Expand Document
Documentation

Table of contents

  1. API
    1. Obtaining API Key
  2. Endpoints
    1. Movies API
      1. Usage
      2. Parameters
      3. Example
    2. My Limits
    3. My lists
    4. User lists
    5. List information
    6. List items
    7. TOP lists
    8. Lists search
    9. Ratings

API

API service allows you to access information about ratings, votes, streaming services and more

Obtaining API Key

Generate your API key in MDBList Preferences

Endpoints

Movies API

Movies API service allows you to access information about ratings, votes, streaming services and more

Usage

Send your requests with GET to:

https://mdblist.com/api/?apikey=[yourkey]&

Parameters

Parameter Description Options Default Value
i A valid IMDb ID    
t A valid Trakt ID    
tm A valid TMDb ID    
tv A valid TVDB ID   Defaults to show
mal A valid MAL ID   Ignores mediatype
m Media type movie, show movie
Parameter Description Options Default Value
s Title to search for Any string  
sc Limit results by score From 0 to 100  
o Order results by score match  
y Year to limit title search Valid year YYYY  
l Limits results returned From 1 to 100 50

Example

Get information about specific movie:

https://mdblist.com/api/?apikey=[yourkey]&i=tt0073195

Search for a movie or show:

https://mdblist.com/api/?apikey=[yourkey]&s=jaws

My Limits

Returns list of User Lists

GET https://mdblist.com/api/user/

Response

{
    "limits":{
        "supporter":true,
        "rating_ids":100,
        "api_requests":25000,
    }
}

My lists

Returns all lists

GET https://mdblist.com/api/lists/user/

Response

[
    {
        "id":13,
        "name":"Top Watched Movies of The Week for KiDS",
        "slug":"top-watched-movies-of-the-week-for-kids",
        "items":13,
        "likes":50,
        "private":false,
        "mediatype":"movie",
        "description":"",
    },
    {
        "id":14,
        "name":"Top Watched Movies of The Week / >60",
        "slug":"top-watched-movies-of-the-week",
        "items":72,
        "likes":244,
        "private":false,
        "mediatype":"movie",
        "description":"",
    }
]

User lists

Returns list of User Lists

GET https://mdblist.com/api/lists/user/{id}/
id: user id

Response

[
    {
        "id":13,
        "name":"Top Watched Movies of The Week for KiDS",
        "slug":"top-watched-movies-of-the-week-for-kids",
        "items":13,
        "likes":50,
        "mediatype":"movie",
        "description":"",
    },
    {
        "id":14,
        "name":"Top Watched Movies of The Week / >60",
        "slug":"top-watched-movies-of-the-week",
        "items":72,
        "likes":244,
        "mediatype":"movie",
        "description":"",
    }
]

List information

Returns information about a list

GET https://mdblist.com/api/lists/{id}?apikey={api_key}
id: list id

Response

[
    {
        "id":14,
        "name":"Top Watched Movies of The Week / >60",
        "slug":"top-watched-movies-of-the-week",
        "items":72,
        "likes":244,
        "user_id":3,
        "mediatype":"movie",
        "user_name":"linaspurinis",
        "description":"",
    }
]

List items

Returns list items

GET https://mdblist.com/api/lists/{id}/items?apikey={api_key}
id: list id

Response

[
    {
        "id":496243,
        "rank":1,
        "adult":0,
        "title":"Parasite",
        "imdb_id":"tt6751668",
        "mediatype":"movie",
        "release_year":2019,
        "language":"en",
        "spoken_language":"en",
    },
    {
        "id":361743,
        "rank":2,
        "adult":0,
        "title":"Top Gun: Maverick",
        "imdb_id":"tt1745960",
        "mediatype":"movie",
        "release_year":2022,
        "language":"en",
        "spoken_language":"en",
    },
]

TOP lists

Returns top-100 lists by likes

GET https://mdblist.com/api/lists/top?apikey={api_key}

Response

[
    {
        "id":2194,
        "name":"Latest TV Shows",
        "slug":"latest-tv-shows",
        "items":200,
        "likes":473,
        "user_id":1230,
        "mediatype":"show",
        "user_name":"garycrawfordgc",
        "description":"",
    },
    {
        "id":14,
        "name":"Top Watched Movies of The Week / >60",
        "slug":"top-watched-movies-of-the-week",
        "items":72,
        "likes":244,
        "user_id":3,
        "mediatype":"movie",
        "user_name":"linaspurinis",
        "description":"",
    },
}

Search public lists by title

GET https://mdblist.com/api/lists/search?s={query}&apikey={api_key}
query: List Title to search

Response

[
    {
        "id":14,
        "name":"Top Watched Movies of The Week / >60",
        "slug":"top-watched-movies-of-the-week",
        "items":72,
        "likes":244,
        "user_id":3,
        "mediatype":"movie",
        "user_name":"linaspurinis",
        "description":"",
    },
]

Ratings

Bulk rating request. Provide list if tmdb ids with media_type and return_rating

POST https://mdblist.com/api/rating/{media_type}/{return_rating}?apikey={api_key}
media_type: ['movie','show']
return_rating: ['trakt', 'imdb', 'tmdb', 'letterboxd', 'tomatoes', 
                'audience', 'metacritic', 'rogerebert', 'mal', 'score', 'score_average']

Payload

{
    "ids": 
        [923, 990, 545611],
    "provider": "tmdb"
}
ids: List of mediatype IDs by type {provider}
provider: ['tmdb','imdb']

Response

{
    "rating": {"923": 4.0, "990": 4.0, "545611": 4.5}, 
    "rating_type": "letterboxd", 
    "mediatype": "movie",
    "provider": "tmdb"
}