API des séries TV

Obtenir les détails d'une série TV

GET /3/tv/{series_id} renvoie la fiche de base d'une série : noms, résumé, statut, genres, chaînes, liste des saisons et pointeurs vers le dernier et le prochain épisode. L'identifiant est l'identifiant numérique de série TMDB : une série que vous stockez sous 1396 garde cet identifiant ici. Les identifiants de films et de séries sont des espaces distincts : stockez donc toujours le type de média à côté du nombre.

L'exemple demande Breaking Bad en anglais et ajoute ses classifications par âge et ses notes externes dans le même appel.

curl -sSf "https://api.amodb.dev/3/tv/1396?language=en-US&append_to_response=content_ratings,ratings" \
  -H "Authorization: Bearer $AMODB_KEY"

const params = new URLSearchParams({ language: 'en-US', append_to_response: 'content_ratings,ratings' });
const res = await fetch(`https://api.amodb.dev/3/tv/1396?${params}`, {
  headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` },
});
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const show = await res.json();
const us = show.content_ratings.results.find((r) => r.iso_3166_1 === 'US');
console.log(show.name, show.status, show.number_of_seasons, us?.rating);

import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/tv/1396",
    params={"language": "en-US", "append_to_response": "content_ratings,ratings"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
show = r.json()
us = next((x for x in show["content_ratings"]["results"] if x["iso_3166_1"] == "US"), None)
print(show["name"], show["status"], show["number_of_seasons"], us and us["rating"])

<?php
$url = 'https://api.amodb.dev/3/tv/1396?' . http_build_query([
    'language' => 'en-US',
    'append_to_response' => 'content_ratings,ratings',
]);
$ch = curl_init($url);
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");
}
$show = json_decode($body, true);
echo $show['name'], ' ', $show['status'], ' ', $show['number_of_seasons'], PHP_EOL;

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
	"os"
	"time"
)

type Show struct {
	Name             string `json:"name"`
	Status           string `json:"status"`
	NumberOfSeasons  int    `json:"number_of_seasons"`
	NumberOfEpisodes int    `json:"number_of_episodes"`
	Next             *struct {
		AirDate string `json:"air_date"`
	} `json:"next_episode_to_air"`
}

func main() {
	q := url.Values{"language": {"en-US"}}
	req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/tv/1396?"+q.Encode(), 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 s Show
	if err := json.NewDecoder(res.Body).Decode(&s); err != nil {
		panic(err)
	}
	next := "none scheduled"
	if s.Next != nil {
		next = s.Next.AirDate
	}
	fmt.Println(s.Name, s.Status, s.NumberOfSeasons, s.NumberOfEpisodes, next)
}

Paramètres

• series_idcheminobligatoire
  Identifiant numérique de la série, par exemple 1396.
• api_keyrequêtel'un des deux
  Votre clé. Utilisez-la ou l'en-tête Authorization: Bearer.
• languagerequête
  Balise TMDB comme en-US, uk-UA ou es-ES. 14 langues de base sont servies. Par défaut en-US.
• append_to_responserequête
  Liste de sous-ressources séparées par des virgules à fusionner dans la réponse, jusqu'à 20 valeurs.

Champs de la réponse

Exemple de réponse

GET /3/tv/1396?language=en-US&append_to_response=content_ratings,ratings, avec les longs tableaux et textes raccourcis :

{
  "adult": false,
  "backdrop_path": "/ycFcYYnzVc8mWw41neszGPMyKc3.jpg",
  "created_by": [],
  "episode_run_time": [
    48,
    49
  ],
  "first_air_date": "2008-01-20",
  "genres": [
    {
      "id": 18,
      "name": "Drama"
    },
    {
      "id": 80,
      "name": "Crime"
    }
  ],
  "homepage": "",
  "id": 1396,
  "in_production": false,
  "languages": [
    "en"
  ],
  "last_air_date": "2013-09-29",
  "last_episode_to_air": {
    "air_date": "2013-09-29",
    "episode_number": 16,
    "episode_type": "standard",
    "id": 62161,
    "name": "פלינה",
    "overview": "הסדרה זוכת הפרסים מגיעה לסיום דרמתי בפרק החותם אותה.",
    "production_code": "",
    "runtime": 56,
    "season_number": 5,
    "show_id": 1396,
    "still_path": "/pA0YwyhvdDXP3BEGL2grrIhq8aM.jpg",
    "vote_average": 0,
    "vote_count": 0
  },
  "name": "Breaking Bad",
  "next_episode_to_air": null,
  "networks": [
    {
      "id": 174,
      "logo_path": "/pmvRmATOCaDykE6JrVoeYxlFHw3.png",
      "name": "AMC",
      "origin_country": "US"
    }
  ],
  "number_of_episodes": 62,
  "number_of_seasons": 5,
  "origin_country": [
    "US"
  ],
  "original_language": "en",
  "original_name": "Breaking Bad",
  "overview": "Walter White, a New Mexico chemistry teacher, is diagnosed with Stage III cancer and given a prognosis of o...",
  "popularity": 268.4968,
  "poster_path": "/anFx9aTOOYqgS3v7x3R84Kz67ly.jpg",
  "production_companies": [
    {
      "id": 2605,
      "logo_path": null,
      "name": "Gran Via Productions",
      "origin_country": "US"
    },
    {
      "id": 11073,
      "logo_path": "/wHs44fktdoj6c378ZbSWfzKsM2Z.png",
      "name": "Sony Pictures Television",
      "origin_country": "US"
    }
  ],
  "production_countries": [
    {
      "iso_3166_1": "US",
      "name": "United States of America"
    }
  ],
  "seasons": [
    {
      "air_date": "2009-02-17",
      "episode_count": 9,
      "id": 3577,
      "name": "特别篇",
      "overview": "",
      "poster_path": "/ikBSCmgG5Z4jequUUAjKpf1QG3T.jpg",
      "season_number": 0,
      "vote_average": 0
    },
    {
      "air_date": "2008-01-20",
      "episode_count": 7,
      "id": 3572,
      "name": "Season 1",
      "overview": "High school chemistry teacher Walter White's life is suddenly transformed by a dire medical diagnosis. Stre...",
      "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg",
      "season_number": 1,
      "vote_average": 0
    }
  ],
  "spoken_languages": [
    {
      "english_name": "English",
      "iso_639_1": "en",
      "name": "English"
    },
    {
      "english_name": "Spanish",
      "iso_639_1": "es",
      "name": "Español"
    }
  ],
  "status": "Ended",
  "tagline": "Change the equation.",
  "vote_average": 9,
  "vote_count": 18863,
  "content_ratings": {
    "results": [
      {
        "descriptors": [],
        "iso_3166_1": "AT",
        "rating": "16"
      },
      {
        "descriptors": [],
        "iso_3166_1": "AU",
        "rating": "MA 15+"
      }
    ]
  },
  "ratings": {
    "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
    }
  }
}

Les blocs content_ratings et ratings viennent de append_to_response. Les noms et les résumés dans seasons, last_episode_to_air et next_episode_to_air sont stockés par fiche et peuvent ne pas suivre language, comme le montre le nom d'épisode en hébreu ci-dessus. Lisez le texte localisé des saisons et des épisodes sur le point de terminaison de saison.

Statut et pointeurs d'épisodes

status indique où en est la vie d'une série, et next_episode_to_air indique quand regarder de nouveau.

Une série en cours entre deux saisons a un next_episode_to_air nul : lisez donc null comme « aucune date connue » et non comme « terminée ».

Le tableau seasons liste un résumé par saison, et la saison 0 contient les épisodes spéciaux. Pour lire les épisodes d'une saison, appelez le point de terminaison décrit sur saisons et épisodes.

Points de terminaison de séries associés

Tous les chemins partagent la base https://api.amodb.dev/3, et les points de terminaison avec du texte localisé acceptent aussi language.

Les listes de recommandations et de séries similaires renvoient toujours la page 1 avec 20 éléments. La réponse de lists est paginée avec page, 20 listes par page. Les listes paginées ailleurs dans l'API acceptent page de 1 à 500.

Les classifications par âge reviennent sous forme d'entrées results avec iso_3166_1, rating et descriptors : choisissez donc l'entrée qui correspond au pays du spectateur. Les plateformes de visionnage sont indexées par code pays, et chaque pays contient un link plus des listes flatrate, rent et buy avec provider_id, provider_name, logo_path et display_priority. Les identifiants de plateformes pour filtrer viennent des listes de référence sur genres et listes de référence.

La liste des groupes d'épisodes renvoie id (une chaîne), name, description, type, episode_count, group_count et network. amodb liste les groupes mais ne propose pas de point de terminaison qui renvoie les épisodes d'un groupe. Il ne propose pas non plus les chemins changes de TMDB.

Fusionner plus de données dans un appel

Listez les sous-ressources dans append_to_response et chacune arrive sous sa propre clé. L'appel entier compte une fois dans vos 20, 40 ou 120 requêtes par minute. Jusqu'à 20 valeurs fonctionnent, et les noms inconnus sont ignorés sans erreur. Ces valeurs fonctionnent sur une série :

Erreurs

Un appel en échec renvoie le corps d'erreur TMDB. Un mauvais identifiant donne status_code 34 avec le message « The resource you requested could not be found. »

La liste complète est sur erreurs, et les limites par offre sont sur limites de débit.

Remarques pratiques

• Les détails d'une série et chaque sous-ressource ci-dessus sont mis en cache 6 heures. Interrogez last_episode_to_air au plus quelques fois par jour.
• Demandez la langue que vous affichez. Un overview vide signifie qu'il n'existe pas de traduction : redemandez avec en-US pour un repli.
• Utilisez number_of_seasons comme borne de boucle quand vous récupérez chaque saison, un appel chacune.
• Pour lister des séries au lieu d'en lire une seule, voir recherche, découverte et tendances et listes.