# Valutazioni di film e serie TV > GET /3/movie/{movie_id}/ratings e GET /3/tv/{tv_id}/ratings restituiscono i punteggi IMDb, Kinopoisk, Metacritic, Rotten Tomatoes e TMDB. Ogni fonte è un oggetto con value e votes, oppure null se sconosciuta. IMDb, Kinopoisk e TMDB sono su 10, le altre due su 100. Aggiungi append_to_response=ratings per unirli ai dettagli. ## Endpoint `GET /3/movie/{movie_id}/ratings` ```bash curl "https://api.amodb.dev/3/movie/550/ratings" \ -H "Authorization: Bearer $AMODB_KEY" ``` Risposta: ```json { "id": 550, "imdb": { "value": 8.8, "votes": 2669989 }, "kinopoisk": { "value": 8.7, "votes": null }, "metacritic": { "value": 67, "votes": null }, "rotten_tomatoes": { "value": 81, "votes": null }, "tmdb": { "value": 8.437, "votes": 33042 } } ``` ## Ottenere le valutazioni di un film `GET /3/movie/{movie_id}/ratings` restituisce i punteggi che le fonti di valutazione pubblicano per un film. La risposta ha l'`id` del film e cinque chiavi di fonti: `imdb`, `kinopoisk`, `metacritic`, `rotten_tomatoes` e `tmdb`. Ogni chiave di fonte contiene un oggetto con `value` e `votes`, oppure `null` quando quella fonte non è nota per il titolo. L'esempio carica Fight Club (id 550) e stampa ogni fonte, segnando quelle sconosciute. ```bash curl -sf "https://api.amodb.dev/3/movie/550/ratings" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const res = await fetch('https://api.amodb.dev/3/movie/550/ratings', { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` }, }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const ratings = await res.json(); for (const source of ['imdb', 'kinopoisk', 'metacritic', 'rotten_tomatoes', 'tmdb']) { const score = ratings[source]; console.log(source, score ? `${score.value} (votes: ${score.votes ?? 'unknown'})` : 'not known'); } ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/movie/550/ratings", headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() ratings = r.json() for source in ("imdb", "kinopoisk", "metacritic", "rotten_tomatoes", "tmdb"): score = ratings[source] if score is None: print(source, "not known") else: print(source, score["value"], "votes:", score["votes"] or "unknown") ``` ```php true, CURLOPT_TIMEOUT => 10, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($status !== 200) { throw new RuntimeException("amodb returned $status"); } $ratings = json_decode($body, true); foreach (['imdb', 'kinopoisk', 'metacritic', 'rotten_tomatoes', 'tmdb'] as $source) { $score = $ratings[$source]; echo $source, ' ', $score === null ? 'not known' : $score['value'] . ' votes: ' . ($score['votes'] ?? 'unknown'), PHP_EOL; } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "time" ) type Score struct { Value float64 `json:"value"` Votes *int `json:"votes"` } type Ratings struct { IMDb *Score `json:"imdb"` Kinopoisk *Score `json:"kinopoisk"` Metacritic *Score `json:"metacritic"` RottenTomatoes *Score `json:"rotten_tomatoes"` TMDB *Score `json:"tmdb"` } func show(name string, s *Score) { if s == nil { fmt.Println(name, "not known") return } if s.Votes == nil { fmt.Println(name, s.Value, "votes: unknown") return } fmt.Println(name, s.Value, "votes:", *s.Votes) } func main() { req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/movie/550/ratings", nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY")) client := &http.Client{Timeout: 10 * time.Second} res, err := client.Do(req) if err != nil { panic(err) } defer res.Body.Close() if res.StatusCode != http.StatusOK { panic(res.Status) } var r Ratings if err := json.NewDecoder(res.Body).Decode(&r); err != nil { panic(err) } show("imdb", r.IMDb) show("kinopoisk", r.Kinopoisk) show("metacritic", r.Metacritic) show("rotten_tomatoes", r.RottenTomatoes) show("tmdb", r.TMDB) } ``` ### Parametri | Parametro | In | Obbligatorio | Descrizione | | ---------- | -------- | ------------ | ------------------------------------------------------------- | | `movie_id` | percorso | sì | ID numerico del film, per esempio `550`. | | `api_key` | query | uno dei due | La tua chiave. Usa questa o l'header `Authorization: Bearer`. | ### Campi della risposta | Campo | Tipo | Note | | ----------------- | -------------- | -------------------------------------------------------------------------------------------------- | | `id` | intero | ID del film. Assente quando usi `append_to_response`. | | `imdb` | oggetto o null | Punteggio IMDb, su 10 con un decimale. | | `kinopoisk` | oggetto o null | Punteggio Kinopoisk, su 10 con un decimale. | | `metacritic` | oggetto o null | Punteggio Metacritic, su 100 come intero. | | `rotten_tomatoes` | oggetto o null | Punteggio Rotten Tomatoes, su 100 come intero. | | `tmdb` | oggetto o null | Punteggio degli utenti TMDB, su 10 con fino a tre decimali. | | `value` | numero | Dentro ogni oggetto di fonte. Il punteggio sulla scala propria di quella fonte. | | `votes` | intero o null | Dentro ogni oggetto di fonte. Numero di voti dietro il punteggio, oppure `null` quando non è noto. | Leggi le cinque chiavi di fonte per nome e salta qualsiasi altra chiave. Le chiavi di fonte arrivano sempre nello stesso ordine: `imdb`, `kinopoisk`, `metacritic`, `rotten_tomatoes`, `tmdb`. ### Risposta di esempio ```json { "id": 550, "imdb": { "value": 8.8, "votes": 2669989 }, "kinopoisk": { "value": 8.7, "votes": null }, "metacritic": { "value": 67, "votes": null }, "rotten_tomatoes": { "value": 81, "votes": null }, "tmdb": { "value": 8.437, "votes": 33039 } } ``` Qui solo IMDb e TMDB hanno un numero di voti. Kinopoisk, Metacritic e Rotten Tomatoes hanno un punteggio e un numero di voti `null`. ## Ottenere le valutazioni di una serie TV `GET /3/tv/{tv_id}/ratings` ha le stesse chiavi e le stesse regole sul null. Passa l'ID della serie, per esempio `1396` per Breaking Bad. | Metodo e percorso | Restituisce | Parametri | | --------------------------------- | ------------------- | ---------- | | `GET /3/movie/{movie_id}/ratings` | `id` e cinque fonti | `movie_id` | | `GET /3/tv/{tv_id}/ratings` | `id` e cinque fonti | `tv_id` | ```bash curl -sf "https://api.amodb.dev/3/tv/1396/ratings" -H "Authorization: Bearer $AMODB_KEY" ``` Breaking Bad non ha un punteggio Metacritic, quindi quella fonte è `null`: ```json { "id": 1396, "imdb": { "value": 9.5, "votes": 2671962 }, "kinopoisk": { "value": 8.9, "votes": null }, "metacritic": null, "rotten_tomatoes": { "value": 96, "votes": null }, "tmdb": { "value": 9, "votes": 18863 } } ``` ## Aggiungere le valutazioni a una chiamata di dettagli `append_to_response=ratings` funziona sui dettagli di film e serie TV. L'oggetto arriva sotto la chiave `ratings` accanto ai campi consueti, senza un `id` proprio. Una pagina di lista richiede una richiesta per titolo invece di due. | Richiesta | Dove compaiono i punteggi | | ----------------------------------------------- | ---------------------------------------------- | | `/3/movie/550?append_to_response=ratings` | `ratings` nella scheda del film | | `/3/tv/1396?append_to_response=credits,ratings` | `ratings` e `credits` nella scheda della serie | Vedi [dettagli del film](https://amodb.dev/it/movies/) e [serie TV](https://amodb.dev/it/tv-series/) per gli altri valori che puoi aggiungere. ## Fonti e valori null Una fonte null non è un punteggio pari a zero. Significa che il punteggio manca per il titolo. | Chiave | Fonte | Scala | Etichetta da mostrare | | ----------------- | --------------- | ---------- | --------------------- | | `imdb` | IMDb | da 0 a 10 | IMDb | | `kinopoisk` | Kinopoisk | da 0 a 10 | Kinopoisk | | `metacritic` | Metacritic | da 0 a 100 | Metacritic | | `rotten_tomatoes` | Rotten Tomatoes | da 0 a 100 | Rotten Tomatoes | | `tmdb` | TMDB | da 0 a 10 | TMDB | La copertura varia da titolo a titolo, quindi scrivi il codice per gestire il null, non per un elenco fisso di fonti. Una qualsiasi delle cinque chiavi può essere null per qualsiasi titolo. ## In cosa le valutazioni differiscono da vote_average I campi `vote_average` e `vote_count` di una scheda di film o serie sono il punteggio degli utenti TMDB. La chiave `tmdb` porta lo stesso punteggio nella stessa forma delle altre quattro, quindi una sola chiamata dà tutte e cinque le fonti in un unico formato. Ogni fonte ha un proprio pubblico e una propria scala. Non farne la media e non confrontare un valore di una fonte con il numero di voti di un'altra. ## Mostrare le valutazioni in un'app Mostra solo le fonti presenti. Un breve elenco di badge basta per una scheda. Aggiungi la scala così chi legge distingue 8.8 su 10 da 67 su 100. ```js const labels = { imdb: ['IMDb', 10], kinopoisk: ['Kinopoisk', 10], metacritic: ['Metacritic', 100], rotten_tomatoes: ['Rotten Tomatoes', 100], tmdb: ['TMDB', 10], }; function badges(ratings) { return Object.entries(labels) .filter(([key]) => ratings[key]) .map(([key, [label, max]]) => `${label} ${ratings[key].value}/${max}`); } ``` Mostra l'etichetta con ogni valore. Quando tutte e cinque sono null, nascondi il blocco invece di mostrare badge vuoti. ## Errori Gli errori mantengono il corpo di errore TMDB, dove `success` è false e `status_code` indica il problema. Un titolo senza punteggi non è tra questi. | HTTP | status_code | Quando | | ---- | ----------- | --------------------------------------------------------------------- | | 401 | 7 | La chiave manca o è sbagliata. | | 402 | 36 | Il periodo del piano è terminato. | | 404 | 34 | Nessun film o serie con quell'ID. | | 429 | 25 | Oltre le tue richieste al minuto. Attendi i secondi di `Retry-After`. | Un punteggio sconosciuto è `null`, non un errore. I dettagli sono nelle pagine [errori](https://amodb.dev/it/errors/) e [limiti di richieste](https://amodb.dev/it/rate-limits/). ## Note pratiche - Le valutazioni restano in cache sull'edge per 6 ore, come i dettagli. Aggiornarle più spesso restituisce lo stesso corpo. - Una richiesta con `append_to_response=ratings` conta come una sola richiesta nelle tue 20, 40 o 120 richieste al minuto. - Salva i punteggi con la data in cui li hai recuperati. I voti crescono nel tempo e i numeri si muovono. - Per associare prima un ID IMDb o Kinopoisk a un titolo, usa la [ricerca per ID esterno](https://amodb.dev/it/find-by-external-id/). Per le sensazioni invece dei punteggi, vedi [mood](https://amodb.dev/it/moods/). ## Domande e risposte ### Perché una fonte è null? Null significa che il punteggio manca o è zero per quel titolo. Un'uscita recente o un film regionale ha spesso meno fonti di uno famoso, quindi gestisci sempre null prima di formattare un numero. Anche il campo votes può essere null. ### In cosa è diverso da vote_average? Il campo vote_average di una scheda dei dettagli è solo il punteggio degli utenti TMDB. L'endpoint delle valutazioni lo restituisce di nuovo sotto la chiave tmdb, con tre decimali, e aggiunge le altre quattro fonti, ciascuna come value e votes. ### Posso fare la media dei cinque punteggi? No. IMDb, Kinopoisk e TMDB sono su 10, mentre Metacritic e Rotten Tomatoes sono su 100. Ogni fonte ha anche un proprio pubblico, e alcune sono null. Mostra affiancate le fonti che hai, con le loro etichette. ### La chiamata delle valutazioni costa richieste in più? È una richiesta come le altre. Con append_to_response=ratings i punteggi arrivano dentro una chiamata di dettagli, quindi usi uno slot di richiesta al minuto invece di due. ## Pagine correlate - [API dei dettagli del film](https://amodb.dev/it/movies/): API dettagli film con gli stessi percorsi e JSON di TMDB v3. Ottieni un film per ID, aggiungi crediti, valutazioni e mood con append_to_response, in 14 lingue. - [API delle serie TV](https://amodb.dev/it/tv-series/): API serie TV con gli stessi percorsi e JSON di TMDB v3. Ottieni una serie per ID con stagioni, emittenti e prossimo episodio, più classificazioni e piattaforme. - [Ricerca per ID esterno](https://amodb.dev/it/find-by-external-id/): Cerca un film, una serie o una persona per ID IMDb, TVDB, Wikidata o Kinopoisk con l'endpoint find di TMDB, e leggi ID esterni e dati Wikidata di un titolo. - [Indicatori di mood](https://amodb.dev/it/moods/): API mood dei film con indicatori da 0 a 10 per titolo. Leggi i mood di un film o serie, uniscili con append_to_response=moods e costruisci badge o filtri. - [Limiti di richieste](https://amodb.dev/it/rate-limits/): amodb limita ogni chiave per richieste al minuto in una finestra scorrevole di 60 secondi: 20, 40 o 120 in base al piano. Leggi gli header, gestisci il 429. - [Avvio rapido](https://amodb.dev/it/quickstart/): Fai la prima chiamata ad amodb: ottieni una chiave, richiedi i dettagli di un film in curl, JavaScript, Python, PHP o Go, carica la locandina. Meno di 2 minuti. Aggiornato: 2026-10-18. Source: https://amodb.dev/it/ratings/