API film per ricerca, dettagli e valutazioni

Un'API film che parla TMDB v3 e OMDb

amodb è un'API film indipendente. Parla lo stesso protocollo di TMDB v3 e OMDb, quindi un client scritto per l'uno o per l'altro funziona dopo che hai cambiato l'URL di base in https://api.amodb.dev/3 (oppure https://api.amodb.dev/omdb/ per le chiamate in stile OMDb). Trovi un film con /search/movie, poi lo leggi con /movie/{movie_id} e append_to_response.

Cosa ottieni:

• JSON nel formato TMDB v3, con gli stessi percorsi e gli stessi parametri di query.
• Titoli e trame in 14 lingue, scelte con language.
• Cast, troupe, trailer, parole chiave, immagini e date di uscita tramite append_to_response.
• Valutazioni da IMDb, Kinopoisk, Metacritic, Rotten Tomatoes e TMDB, quando sono note.
• Locandine da https://img.amodb.dev/t/p/{size}/{file}, senza chiave.

Quali dati ottieni

Parti in 3 passaggi

1. Scegli un piano nella pagina dei prezzi. I piani differiscono solo per la frequenza: 20, 40 o 120 richieste al minuto.
2. Crea una chiave nella dashboard del tuo account. Una chiave è di 32 caratteri esadecimali minuscoli.
3. Chiama l'endpoint con la chiave nel parametro api_key o in un header Authorization: Bearer. Vedi autenticazione.

Esempio di richiesta

L'esempio trova Inception per titolo, prende il primo risultato e legge il film con cast, trailer e valutazioni in un'altra chiamata. In totale sono due richieste.

# 1. find the id
curl -s "https://api.amodb.dev/3/search/movie?query=inception&language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"

# 2. read the movie with extras
curl -s "https://api.amodb.dev/3/movie/27205?language=en-US&append_to_response=credits,videos,ratings" \
  -H "Authorization: Bearer $AMODB_KEY"

const base = 'https://api.amodb.dev/3';
const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` };

async function get(path, params) {
  const res = await fetch(`${base}${path}?${new URLSearchParams(params)}`, { headers });
  if (res.status === 429) {
    throw new Error(`Over the limit, retry in ${res.headers.get('Retry-After')} s`);
  }
  if (!res.ok) throw new Error(`amodb returned ${res.status}`);
  return res.json();
}

const found = await get('/search/movie', { query: 'inception', language: 'en-US' });
if (!found.results.length) throw new Error('No match');

const movie = await get(`/movie/${found.results[0].id}`, {
  language: 'en-US',
  append_to_response: 'credits,videos,ratings',
});
const director = movie.credits.crew.find((c) => c.job === 'Director');
console.log(movie.title, movie.release_date, movie.runtime, director?.name);
console.log('IMDb', movie.ratings.imdb?.value);

La risposta ridotta. Della scheda del film sono tenuti solo alcuni campi, credits è tagliato a un membro del cast e al regista, e il blocco videos è omesso.

{
  "genres": [
    {
      "id": 12,
      "name": "Adventure"
    },
    {
      "id": 28,
      "name": "Action"
    },
    {
      "id": 80,
      "name": "Crime"
    }
  ],
  "id": 27205,
  "imdb_id": "tt1375666",
  "poster_path": "/xlaY2zyzMfkhk0HSC5VUwzoZPU1.jpg",
  "release_date": "2010-07-15",
  "runtime": 148,
  "title": "Inception",
  "credits": {
    "cast": [
      {
        "adult": false,
        "gender": 2,
        "id": 6193,
        "known_for_department": "Acting",
        "name": "Leonardo DiCaprio",
        "original_name": "Leonardo DiCaprio",
        "popularity": 9.3213,
        "profile_path": "/wo2hJpn04vbtmh0B9utCFdsQhxM.jpg",
        "character": "Dom Cobb",
        "credit_id": "52fe4534c3a368484e04de03",
        "order": 0
      }
    ],
    "crew": [
      {
        "adult": false,
        "gender": 2,
        "id": 525,
        "known_for_department": "Directing",
        "name": "Christopher Nolan",
        "original_name": "Christopher Nolan",
        "popularity": 8.578,
        "profile_path": "/xuAIuYSmsUzKlUMBFGVZaWsY3DZ.jpg",
        "credit_id": "5e83ac2ee33f830018359a00",
        "department": "Directing",
        "job": "Director"
      }
    ]
  },
  "ratings": {
    "imdb": {
      "value": 8.8,
      "votes": 2877173
    },
    "kinopoisk": {
      "value": 8.7,
      "votes": null
    },
    "metacritic": {
      "value": 74,
      "votes": null
    },
    "rotten_tomatoes": {
      "value": 86,
      "votes": null
    },
    "tmdb": {
      "value": 8.373,
      "votes": 40457
    }
  }
}

Modi per trovare un film

Scegli la chiamata che corrisponde a ciò che hai già.

Salva entrambi gli ID. L'id numerico è la chiave per ogni altra chiamata, e imdb_id collega i tuoi dati ad altri sistemi. Le regole di ricerca sono nella pagina ricerca per ID esterno.

Campi vuoti e ricerche fallite

I dati reali sui film hanno delle lacune, quindi scrivi il codice di visualizzazione tenendone conto. Una ricerca senza risultati non è un errore: restituisce HTTP 200 con un array results vuoto. Un ID sconosciuto è un errore.

L'elenco completo degli errori è nella pagina errori.

Restare nel limite di richieste

Una ricerca e una chiamata di dettagli costano una richiesta ciascuna. A 20 richieste al minuto sono dieci ricerche di titoli al minuto, a 120 richieste al minuto sono sessanta. Una risposta dalla cache edge conta comunque, perché il controllo della chiave e il limite di richieste vengono prima della cache. Tieni una cache tua per le ricerche ripetute e leggi X-RateLimit-Remaining per vedere quanto resta del minuto. Quando ricevi un 429, attendi i secondi di Retry-After. I limiti per piano sono nella pagina limiti di richieste.

Confronto

Prezzi

L'accesso è prepagato per 1, 3, 6, 12 o 24 mesi, con uno sconto di 0, 10, 20, 30 e 40 per cento sui periodi più lunghi. Non c'è rinnovo automatico né un piano gratuito. Ogni piano dà accesso a tutti i dati, e i piani differiscono solo per la frequenza: 20, 40 o 120 richieste al minuto. Scegline uno nella pagina dei prezzi e fai la tua prima chiamata in pochi minuti.