Python: effettuare ricerche con le API di The Movie Database

In questo articolo vedremo come effettuare ricerche usando le API di The Movie Database con Python.

Dopo aver ottenuto la nostra chiave API dalla piattaforma, la possiamo memorizzare in un file .env da usare nella nostra applicazione.

API_KEY=chiave_api

Dobbiamo installare i moduli python-dotenv (per leggere il file .env) e requests (per effettuare le richieste HTTP alle API).

Fatto questo, definiamo le specifiche della nostra applicazione, che dovrà:

1. accettare come input utente un termine di ricerca e validarlo in modo preventivo
2. effettuare una richiesta GET verso un endpoint specifico delle API di The Movie Database e restituire i risultati eventualmente ottenuti
3. formattare l'output JSON in modo da avere il titolo del film, l'anno di uscita e la trama in formato testuale leggibile.

Come primo passo, definiamo la logica del reperimento dei dati con una funzione specifica.

import sys
import os
import requests
from dotenv import load_dotenv

load_dotenv()


def get_tmdb_api_data(endpoint=None, query=None):
    if endpoint is None:
        return None
    api_url = f'https://api.themoviedb.org/3/{endpoint}'
    params = {'api_key': os.getenv('API_KEY')}
    if query is not None:
        params['query'] = query
    try:
        response = requests.get(api_url, params=params, allow_redirects=True)
        return response.json()
    except requests.exceptions.RequestException:
        return None

La chiamata iniziale alla funzione load_dotenv() serve a caricare in memoria la variabile d'ambiente API_KEY ottenuta dal file .env precedentemente creato. Quindi il valore di tale variabile sarà disponibile invocando il metodo getenv() del modulo core os.

La nostra funzione restituirà il valore None se non viene fornito l'endpoint obbligatorio delle API o se la richiesta HTTP dovesse sollevare un'eccezione. In caso contrario, vengono restituiti i valori in formato JSON. Poiché in futuro potremmo voler riusare la nostra funzione per altre richieste diverse dalla ricerca, il parametro query è stato reso opzionale.

Ora dobbiamo definire il codice che effettua la ricerca in base al termine fornito dall'utente.

def search_tmdb_api(search_term=None):
    movies = []
    if search_term is None:
        return None
    if len(search_term) == 0:
        return None
    results = get_tmdb_api_data('search/movie', search_term)
    if results is None:
        return None
    data = results.get('results')
    if data is None or len(data) == 0:
        return movies
    for datum in data:
        movie = {'title': datum.get('title'), 'plot': datum.get(
            'overview'), 'date': datum.get('release_date')}
        movies.append(movie)
    return movies

Se il termine di ricerca non viene definito o se è vuoto, viene restituito il valore None. Al contrario, se l'output JSON accessibile come dizionario non presenta la chiave results o se tale chiave è una lista vuota, viene restituita una lista vuota che indica in questo caso che non sono presenti risultati.

A questo punto effettuiamo un loop sulla lista data e popoliamo la lista di output con dei dizionari aventi come valori il titolo, la data e la trama del film corrente. Infine, restituiamo la lista precedentemente popolata.

Ora dobbiamo formattare in formato testuale i risultati eventualmente ottenuti.

def format_tmdb_api_results(results=None):
    if isinstance(results, list) and len(results) > 0:
        output = []
        for result in results:
            date = result.get('date')
            year = ''
            if date is not None:
                date_parts = date.split('-')
                year = date_parts[0]
            entry = f'{result.get("title", "")}\n{year}\n{result.get("plot", "")}'
            output.append(entry)
        return '\n\n'.join(output)
    return ''

Restituiamo una stringa vuota se l'input della funzione non è una lista o se tale lista è vuota. In caso contrario, effettuiamo un loop sulla lista di input popolando una lista di output che trasformeremo infine in stringa estraendo l'anno di uscita del film dalla chiave date che è nel formato yyyy-mm-dd e che quindi può essere facilmente separata nei suoi componenti. In questo caso una conversione preliminare in un oggetto data per ottenere l'anno avrebbe appesantito inutilmente l'esecuzione del codice, soprattutto se si tiene presente che l'output finale è una stringa.

Infine, definiamo la nostra funzione principale:

def main():
    search_term = input('Query: ')
    results = search_tmdb_api(search_term)
    if results is None:
        print('Request error')
        sys.exit(1)
    if len(results) == 0:
        print('No results')
        sys.exit(1)
    print(format_tmdb_api_results(results))
    sys.exit(0)


if __name__ == '__main__':
    main()

È sempre buona norma comunicare il risultato dell'esecuzione del nostro codice utilizzando un codice standard di uscita, che in questo caso è 1 in caso di errore o di risultati assenti e 0 in caso di successo.