Searching for specific content in netflix with Python

Intro

During these vacations I wanted to take advantage of my free time to complete at least one TV show. Avoiding unfinished ones, since I don't want to get hooked again to series that end up being canceled. On this opportunity we will be looking at the Netflix platform, which as we well know has a reputation of cancelling many of the series it produces.

Solution

Let's filter the content to find TV series with Ended status. On the TMDB website we can see complete information about series and movies. It allows us to filter content by platform and even by region, but unfortunately it does not allow filtering by status. However, from its API, we can access to a lot of filters and among them, we can filter by status.

TMDB API

Discover TV Series

Log in to the TMDB developer portal, and go to the Discover series section. In this section we can see a list of available endpoints^[1], their documentation and a small interface to test the API.

In this last section we will be able to use the API directly, and it also shows us the code to perform the query in different programming languages. Copy the API key that you can see in the “Credentials” field or in the example code.

In the endpoint documentation you will find a long list of filters, but we will only use some of them.

• with_status: The status Ended is represented by the value 3.
• with_watch_providers: ID of the platform on which the content should be available, it is necessary to specify the region. The Netflix platform ID is 8.
• watch_region: here we specify the region, which in my case will be VE.
• with_networks: to get original series from the specified company. The Netflix network ID is 213.

The values currently mentioned were extracted from the detailed content, from a Netflix original series, obtained from the TMDB API.

In the case of the status for TV series it is not specified in the documentation, but there is a clear reference in the TMDB forum.

Preparing the code

We start by creating the basic structure of the project. From Linux console we do it running the following commands.

# Create a directory for the project and get in
mkdir project1
cd project1

# Create a python virtual environment and activate it
python3 -m venv venv
source ./venv/bin/activate

# Update pip and install project requirements
pip install --upgrade pip
pip install requests rich python-dotenv

# Create python files we will write later
touch models.py main.py

Now we create a python module with the object models that we will get from the API, based on the results of the discover function.

models.py file:

"""models.py"""

from pydantic import BaseModel, Field


class MediaContent(BaseModel):
    """Media Content class"""

    id_: int = Field(alias="id")
    vote_average: float
    

class TVshow(MediaContent):
    """TV show content"""

    original_name: str
    name: str
    first_air_date: str


class TmdbApiSearchResponse(BaseModel):
    """Response from TMDB API"""
    page: int
    results: list[TVshow | Movie]
    total_pages: int
    total_results: int

Now we create the main module (discover.py), where we will import the models.py module and write all the functionality. It is necessary to create a file called .env inside our project, where we are going to store our API key as an environment variable.

.env file:

TMDB_API_KEY= put here your api key

Import all the necessary modules, declare the constants and load the environment variable with our secret key in the main module.

discover.py file:

"""Module to discover content in TMDB"""

import os

import requests
from dotenv import load_dotenv
from rich.console import Console
from rich.table import Table
from typer import Typer

from models import TmdbApiSearchResponse

load_dotenv()
TMDB_API_KEY = os.environ["TMDB_API_KEY_2"]

app = Typer()

# CONSTANTS
COUNTRY: str = "VE"
NETFLIX_ID: int = 8
NETFLIX_NETWORK_ID: int = 213
STATUS_ENDED: int = 3
CONTENT_URL: str = "https://themoviedb.org/tv/"

...

Now, in the same module we are going to create the function to "get TV series".

...

def get_ended_tv_shows(netflix_originals: bool = False):
    """This function returns the results from the TMDB API."""

    api_discover = "https://api.themoviedb.org/3/discover/tv"

    headers = {
        "accept": "application/json", 
        "Authorization": f"Bearer {TMDB_API_KEY}"
    }
    params = {
        "include_adult": True,
        "watch_region": COUNTRY,
        "language": "en-US",
        "with_status": STATUS_ENDED,
        "with_watch_providers": NETFLIX_ID,
        "with_original_language": "en",
    }
    if netflix_originals:
        params["with_networks"] = NETFLIX_NETWORK_ID

    response = requests.get(
        url=api_discover, headers=headers, params=params, timeout=30
    )
    return response.json()

...

And finally, we are going to model that data and present it in a table.

...

@app.command()
def discover_netflix_series(original: bool = False):
    """Main function"""
    response = TmdbApiSearchResponse(
        **get_ended_tv_shows(netflix_originals=original)
    )
    title = "TOP Ended TV Shows in Netflix"
    if original:
        title += " (originals)"
    table = Table(title=title, show_header=True, header_style="bold")
    table.add_column("Name", style="italic")
    table.add_column("Score", justify="center")
    table.add_column("Link")

    for item in response.results:
        table.add_row(
            item.name,
            f"{item.vote_average:.1f}",
            CONTENT_URL + str(item.id_),
        )

    console = Console()
    console.print(table)


if __name__ == "__main__":
    app()

Results

Here is the first results from TMDB, as of today, of complete series on Netflix available for Venezuela.

$ python discover.py 
                        TOP Ended TV Shows in Netflix                          
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name                           ┃   Score    ┃ Link                            ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ The Blacklist                  │    7.6     │ https://themoviedb.org/tv/46952 │
│ Brooklyn Nine-Nine             │    8.2     │ https://themoviedb.org/tv/48891 │
│ The Flash                      │    7.8     │ https://themoviedb.org/tv/60735 │
│ Prison Break                   │    8.1     │ https://themoviedb.org/tv/2288  │
│ Lucifer                        │    8.5     │ https://themoviedb.org/tv/63174 │
│ Dexter                         │    8.2     │ https://themoviedb.org/tv/1405  │
│ House                          │    8.6     │ https://themoviedb.org/tv/1408  │
│ Breaking Bad                   │    8.9     │ https://themoviedb.org/tv/1396  │
│ Arrested Development           │    8.0     │ https://themoviedb.org/tv/4589  │
│ Suits                          │    8.2     │ https://themoviedb.org/tv/37680 │
│ Vikings                        │    8.1     │ https://themoviedb.org/tv/44217 │
│ Lost                           │    7.9     │ https://themoviedb.org/tv/4607  │
│ Star Trek: The Next Generation │    8.4     │ https://themoviedb.org/tv/655   │
│ Peaky Blinders                 │    8.5     │ https://themoviedb.org/tv/60574 │
│ The Crown                      │    8.2     │ https://themoviedb.org/tv/65494 │
│ Better Call Saul               │    8.7     │ https://themoviedb.org/tv/60059 │
│ Arcane                         │    8.8     │ https://themoviedb.org/tv/94605 │
│ Billions                       │    7.7     │ https://themoviedb.org/tv/62852 │
│ Riverdale                      │    8.4     │ https://themoviedb.org/tv/69050 │
│ The Walking Dead               │    8.1     │ https://themoviedb.org/tv/1402  │
└────────────────────────────────┴────────────┴─────────────────────────────────┘

And here we filter for Netflix original series.

$ python discover.py --original
                    TOP Ended TV Shows in Netflix (originals)                           
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name                           ┃   Score    ┃ Link                             ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Lucifer                        │    8.5     │ https://themoviedb.org/tv/63174  │
│ Arrested Development           │    8.0     │ https://themoviedb.org/tv/4589   │
│ The Crown                      │    8.2     │ https://themoviedb.org/tv/65494  │
│ Arcane                         │    8.8     │ https://themoviedb.org/tv/94605  │
│ Narcos: Mexico                 │    7.9     │ https://themoviedb.org/tv/80968  │
│ The Umbrella Academy           │    8.5     │ https://themoviedb.org/tv/75006  │
│ Sex Education                  │    8.2     │ https://themoviedb.org/tv/81356  │
│ The Last Kingdom               │    8.3     │ https://themoviedb.org/tv/63333  │
│ BoJack Horseman                │    8.6     │ https://themoviedb.org/tv/61222  │
│ Lost in Space                  │    7.5     │ https://themoviedb.org/tv/75758  │
│ Ozark                          │    8.2     │ https://themoviedb.org/tv/69740  │
│ No Good Deed                   │    5.6     │ https://themoviedb.org/tv/241112 │
│ Vikings: Valhalla              │    7.7     │ https://themoviedb.org/tv/116135 │
│ Chilling Adventures of Sabrina │    8.2     │ https://themoviedb.org/tv/79242  │
│ Inspector Gadget               │    6.0     │ https://themoviedb.org/tv/62508  │
│ Grace and Frankie              │    7.7     │ https://themoviedb.org/tv/62320  │
│ Unbreakable Kimmy Schmidt      │    7.2     │ https://themoviedb.org/tv/61671  │
│ Dragons: Race to the Edge      │    8.3     │ https://themoviedb.org/tv/78173  │
│ Orange Is the New Black        │    7.7     │ https://themoviedb.org/tv/1424   │
│ The Madness                    │    6.5     │ https://themoviedb.org/tv/220056 │
└────────────────────────────────┴────────────┴──────────────────────────────────┘  

Conclusion

This way I have been able to find complete series on the Netflix platform. Also, by adjusting the filters we can get different results, for example, searching for content on multiple platforms or on some other specific platform like Apple TV.

I wrote this version of the code some time ago, I am currently creating a version with web interface (Web UI), to facilitate access to all types of users, since this version works from the command line (CLI).

In this case we are getting the first 20 results, pagination will be implemented later.

And of course, you can access the full code in this repository.

1. Definition of endpoint, according to Cloudflare ↩