Notes des films et séries

Obtenir les notes d'un film

GET /3/movie/{movie_id}/ratings renvoie les notes que publient les sources de notation pour un film. La réponse contient l'id du film et cinq clés de sources : imdb, kinopoisk, metacritic, rotten_tomatoes et tmdb. Chaque clé de source contient un objet avec value et votes, ou null quand cette source n'est pas connue pour le titre.

L'exemple charge Fight Club (id 550) et affiche chaque source, en marquant celles qui sont inconnues.

curl -sf "https://api.amodb.dev/3/movie/550/ratings" \
  -H "Authorization: Bearer $AMODB_KEY"

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');
}

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
$ch = curl_init('https://api.amodb.dev/3/movie/550/ratings');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => 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;
}

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)
}

Paramètres

• movie_idcheminobligatoire
  Identifiant numérique du film, par exemple 550.
• api_keyrequêtel'un des deux
  Votre clé. Utilisez-la ou l'en-tête Authorization: Bearer.

Champs de la réponse

Lisez les cinq clés de sources par leur nom et ignorez toute autre clé. Les clés de sources arrivent toujours dans le même ordre : imdb, kinopoisk, metacritic, rotten_tomatoes, tmdb.

Exemple de réponse

{
  "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 }
}

Seuls IMDb et TMDB sont accompagnés d'un nombre de votes ici. Kinopoisk, Metacritic et Rotten Tomatoes ont une note et un nombre de votes null.

Obtenir les notes d'une série

GET /3/tv/{tv_id}/ratings a les mêmes clés et les mêmes règles pour null. Passez l'identifiant de la série, par exemple 1396 pour Breaking Bad.

curl -sf "https://api.amodb.dev/3/tv/1396/ratings" -H "Authorization: Bearer $AMODB_KEY"

Breaking Bad n'a pas de note Metacritic : cette source vaut donc null :

{
  "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 }
}

Ajouter les notes à un appel de détails

append_to_response=ratings fonctionne sur les détails des films et des séries. L'objet arrive sous la clé ratings à côté des champs habituels, sans id propre. Une page de liste demande une requête par titre au lieu de deux.

Voir détails d'un film et séries TV pour les autres valeurs que vous pouvez ajouter.

Sources et valeurs null

Une source null n'est pas une note de zéro. Elle signifie que la note manque pour le titre.

La couverture varie selon le titre : écrivez votre code pour gérer null, pas pour une liste fixe de sources. N'importe laquelle des cinq clés peut valoir null pour n'importe quel titre.

En quoi les notes diffèrent de vote_average

Les champs vote_average et vote_count d'une fiche de film ou de série sont la note des utilisateurs TMDB. La clé tmdb porte la même note, dans la même forme que les quatre autres : un seul appel donne donc les cinq sources dans un seul format.

Chaque source a son propre public et sa propre échelle. N'en faites pas la moyenne et ne comparez pas une valeur d'une source avec le nombre de votes d'une autre.

Afficher les notes dans une application

N'affichez que les sources présentes. Une courte liste de badges suffit pour une carte. Ajoutez l'échelle pour qu'un lecteur distingue 8.8 sur 10 de 67 sur 100.

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}`);
}

Affichez le libellé avec chaque valeur. Quand les cinq valent null, masquez le bloc au lieu d'afficher des badges vides.

Erreurs

Les échecs gardent le corps d'erreur TMDB, où success vaut false et status_code désigne le problème. Un titre sans note n'en fait pas partie.

Une note inconnue est null, pas une erreur. Les détails sont sur erreurs et limites de débit.

Remarques pratiques

• Les notes sont mises en cache 6 heures en périphérie, comme les détails. Les actualiser plus souvent renvoie le même corps.
• Une requête avec append_to_response=ratings compte pour une seule requête dans vos 20, 40 ou 120 requêtes par minute.
• Stockez les notes avec la date de leur récupération. Les votes augmentent avec le temps et les chiffres bougent.
• Pour d'abord associer un identifiant IMDb ou Kinopoisk à un titre, utilisez la recherche par identifiant externe. Pour les sensations plutôt que les notes, voir ambiances.