# API des séries TV > Le point de terminaison de séries renvoie une série par id sur GET /3/tv/{series_id} : noms, résumé, statut, saisons, chaînes, genres et pointeurs vers le dernier et le prochain épisode. Le JSON suit TMDB v3 : les clients existants n'ont besoin que d'une nouvelle URL de base. Ajoutez append_to_response pour fusionner classifications, crédits et notes en une requête. ## Point de terminaison `GET /3/tv/{series_id}` ```bash curl "https://api.amodb.dev/3/tv/1396?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` Réponse: ```json { "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 only two years left to live. He becomes filled with a sense of fearlessness and an unrelenting desire to secure his family's financial...", "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" }, { "id": 33742, "logo_path": "/2jdh2sEa0R6y6uT0F7g0IgA2WO8.png", "name": "High Bridge Productions", "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. Street-savvy former student Jesse Pinkman \"teaches\" Walter a new trade.", "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg", "season_number": 1, "vote_average": 0 }, { "air_date": "2009-03-08", "episode_count": 13, "id": 3573, "name": "第 2 季", "overview": "贩卖冰毒的沃尔特老师在毒品交易中越陷越深，这引起了竞争对手的注意并使他在缉毒局的小舅子陷入危险中。", "poster_path": "/zMO024gJxKhTJfWqM0XTYd3SgKj.jpg", "season_number": 2, "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": 8.955, "vote_count": 18871 } ``` ## 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. ```bash curl -sSf "https://api.amodb.dev/3/tv/1396?language=en-US&append_to_response=content_ratings,ratings" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js 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); ``` ```python 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 '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; ``` ```go 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 | Paramètre | Dans | Requis | Description | | -------------------- | ------- | ------------- | --------------------------------------------------------------------------------------------------- | | `series_id` | chemin | oui | Identifiant numérique de la série, par exemple `1396`. | | `api_key` | requête | l'un des deux | Votre clé. Utilisez-la ou l'en-tête `Authorization: Bearer`. | | `language` | requête | non | Balise TMDB comme `en-US`, `uk-UA` ou `es-ES`. 14 langues de base sont servies. Par défaut `en-US`. | | `append_to_response` | requête | non | Liste de sous-ressources séparées par des virgules à fusionner dans la réponse, jusqu'à 20 valeurs. | ### Champs de la réponse | Champ | Type | Remarques | | -------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `id` | entier | Identifiant de la série. | | `name`, `original_name` | chaîne | Titre localisé et titre original. Les noms originaux en japonais ou en coréen restent dans `original_name`. | | `overview`, `tagline` | chaîne | Texte localisé, vide quand il n'existe pas de traduction. | | `first_air_date`, `last_air_date` | chaîne ou null | `YYYY-MM-DD`. | | `status` | chaîne | Cycle de vie, voir le tableau ci-dessous. | | `in_production` | booléen | `true` tant que la série est encore en fabrication. | | `number_of_seasons`, `number_of_episodes` | entier | Totaux, tels que stockés pour la série. | | `episode_run_time` | tableau | Durées typiques des épisodes en minutes, peut être vide. | | `seasons` | tableau | Un résumé par saison avec `id`, `season_number`, `name`, `overview`, `episode_count`, `air_date`, `poster_path`, `vote_average`. | | `last_episode_to_air`, `next_episode_to_air` | objet ou null | Résumés d'épisodes, de la forme des objets de [saisons et épisodes](https://amodb.dev/fr/tv-seasons-episodes/). | | `networks`, `production_companies` | tableau | `id`, `name`, `logo_path`, `origin_country`. | | `production_countries`, `spoken_languages` | tableau | Pays avec `iso_3166_1` et `name`. Langues avec `english_name`, `iso_639_1` et `name`. | | `created_by` | tableau | Créateurs avec `id`, `name`, `profile_path` et `credit_id`. Vide pour la plupart des séries. | | `genres` | tableau | Objets avec `id` et `name`. Les identifiants de genres des séries diffèrent de ceux des films. | | `origin_country`, `original_language`, `languages` | tableau, chaîne | Codes pays et codes de langue. | | `homepage` | chaîne | Site officiel, vide quand il est inconnu. | | `poster_path`, `backdrop_path` | chaîne ou null | À ajouter à `https://img.amodb.dev/t/p/{size}`. Voir [images](https://amodb.dev/fr/images-api/). | | `popularity` | nombre | Score relatif utilisé par la liste des populaires. | | `vote_average`, `vote_count` | nombre, entier | Note agrégée des utilisateurs. | | `adult` | booléen | Toujours `false`. Les titres pour adultes ne sont jamais servis. | ### Exemple de réponse `GET /3/tv/1396?language=en-US&append_to_response=content_ratings,ratings`, avec les longs tableaux et textes raccourcis : ```json { "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](https://amodb.dev/fr/tv-seasons-episodes/). ## 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. | Valeur de `status` | Signification | `next_episode_to_air` | | -------------------------- | -------------------------------------------- | ------------------------------------------------ | | `Returning Series` | En cours de diffusion ou entre deux saisons. | Renseigné quand une date est connue, sinon null. | | `Planned`, `In Production` | Pas encore une série régulière. | Généralement null. | | `Ended` | A terminé sa diffusion. | Null. | | `Canceled` | Arrêtée avant la fin prévue. | Null. | 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](https://amodb.dev/fr/tv-seasons-episodes/). ## 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`. | Méthode et chemin | Renvoie | Paramètres supplémentaires | | ---------------------------------------- | ---------------------------------------------------------------- | -------------------------- | | `GET /tv/{series_id}/alternative_titles` | `{id, results}` avec `iso_3166_1`, `title`, `type`, souvent vide | aucun | | `GET /tv/{series_id}/content_ratings` | Classification par âge pour chaque pays | aucun | | `GET /tv/{series_id}/episode_groups` | Liste d'ordres d'épisodes alternatifs comme DVD ou arc narratif | aucun | | `GET /tv/{series_id}/recommendations` | Une liste de 20 séries recommandées | aucun | | `GET /tv/{series_id}/similar` | Une liste de 20 séries similaires | aucun | | `GET /tv/{series_id}/reviews` | `results` est vide pour la plupart des séries | aucun | | `GET /tv/{series_id}/lists` | Listes publiques qui contiennent la série | `page` | | `GET /tv/{series_id}/watch/providers` | Plateformes de streaming, de location et d'achat par pays | aucun | | `GET /tv/latest` | La fiche de série la plus récente ajoutée | aucun | 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](https://amodb.dev/fr/genres/). 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 : | Valeur | Ajoute | Détails | | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `credits` | Distribution et équipe | [Crédits](https://amodb.dev/fr/credits/) | | `external_ids` | Identifiants comme `imdb_id`, `tvdb_id` et `wikidata_id` | [Recherche par identifiant externe](https://amodb.dev/fr/find-by-external-id/) | | `images`, `videos` | Affiches, images de fond, bandes-annonces | [Images](https://amodb.dev/fr/images-api/), [Vidéos](https://amodb.dev/fr/videos-trailers/) | | `keywords`, `translations` | Tags et textes traduits | [Mots-clés](https://amodb.dev/fr/keywords/), [Traductions](https://amodb.dev/fr/translations/) | | `content_ratings`, `alternative_titles`, `episode_groups`, `lists`, `watch/providers`, `similar`, `recommendations`, `reviews` | Les sous-ressources du tableau ci-dessus | Cette page | | `ratings`, `moods`, `soundtracks`, `wikidata`, `showtimes` | Extras d'amodb | [Notes](https://amodb.dev/fr/ratings/), [Ambiances](https://amodb.dev/fr/moods/), [Bandes originales](https://amodb.dev/fr/soundtracks/), [Séances](https://amodb.dev/fr/showtimes/) | ## 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. » | HTTP | status_code | Quand | | ---- | ----------- | ----------------------------------------------------------------------------------- | | 401 | 7 | La clé est absente ou fausse. | | 402 | 36 | La période de l'offre est terminée. | | 404 | 34 | Aucune série avec cet identifiant, un titre pour adultes, ou un chemin non proposé. | | 405 | 37 | Vous avez appelé une méthode d'écriture comme noter une série. | | 429 | 25 | Au-dessus de vos requêtes par minute. Attendez les secondes de `Retry-After`. | La liste complète est sur [erreurs](https://amodb.dev/fr/errors/), et les limites par offre sont sur [limites de débit](https://amodb.dev/fr/rate-limits/). ## 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](https://amodb.dev/fr/search/), [découverte](https://amodb.dev/fr/discover/) et [tendances et listes](https://amodb.dev/fr/trending-lists/). ## Questions et réponses ### Comment savoir si une série est encore diffusée ? Lisez status avec next_episode_to_air. Une série en cours avec un next_episode_to_air non nul a un épisode programmé. Les séries terminées et annulées y renvoient toujours null, et une série entre deux saisons aussi. ### La fiche de la série contient-elle un id IMDb ? Pas dans la fiche de base, comme dans TMDB. Ajoutez append_to_response=external_ids pour obtenir imdb_id et tvdb_id, ou appelez le point de terminaison find avec un id IMDb pour passer d'un identifiant externe à l'identifiant de la série. ### Puis-je obtenir les notes IMDb et Rotten Tomatoes d'une série ? Oui. Appelez GET /3/tv/{series_id}/ratings ou ajoutez append_to_response=ratings. Vous obtenez les notes IMDb, Kinopoisk, Metacritic, Rotten Tomatoes et TMDB, chacune sous forme de value et votes, ou null quand la note n'est pas connue. ### Combien de temps les données de séries sont-elles mises en cache ? Les détails d'une série et leurs sous-ressources sont mis en cache 6 heures en périphérie : un épisode tout juste diffusé peut donc apparaître dans last_episode_to_air avec ce retard. Les listes comme celle des séries en cours de diffusion sont mises en cache 30 minutes. ## Pages liées - [API des saisons et épisodes de séries TV](https://amodb.dev/fr/tv-seasons-episodes/): API de saisons et d'épisodes aux chemins et au JSON de TMDB v3. Lisez une saison avec tous ses épisodes, ou un épisode avec date de diffusion, durée et image. - [API des crédits](https://amodb.dev/fr/credits/): API crédits aux chemins et au JSON de TMDB v3. Distribution et équipe des films, séries, saisons et épisodes, avec les champs order, department et job. - [Notes des films et séries](https://amodb.dev/fr/ratings/): API de notes de films : scores IMDb, Kinopoisk, Metacritic, Rotten Tomatoes et TMDB d'un titre en un appel, avec null pour toute source inconnue. - [API de séries TV pour les séries, les saisons et les épisodes](https://amodb.dev/fr/tv-show-api/): API de séries TV avec statut, chaînes, saisons, épisodes et next_episode_to_air. JSON compatible TMDB v3 en 14 langues, dès 20 requêtes par minute. - [Erreurs](https://amodb.dev/fr/errors/): Chaque erreur amodb : statut HTTP, status_code et message TMDB, plus la forme d'erreur OMDb. Ce que chacune signifie et ce que votre client doit faire. - [Démarrage rapide](https://amodb.dev/fr/quickstart/): Faites votre premier appel amodb : obtenez une clé, demandez un film en curl, JavaScript, Python, PHP ou Go, puis chargez l'affiche. En moins de 2 minutes. Mis à jour: 2026-10-19. Source: https://amodb.dev/fr/tv-series/