Jak poznám, zda se seriál ještě vysílá?

Čtěte status společně s next_episode_to_air. Pokračující seriál s ne-null next_episode_to_air má naplánovanou epizodu. Skončené a zrušené seriály tam vždy vracejí null a seriál mezi sezónami také.

Obsahuje záznam seriálu ID z IMDb?

V základním záznamu ne, stejně jako u TMDB. Přidejte append_to_response=external_ids a získáte imdb_id a tvdb_id, nebo zavolejte endpoint find s ID z IMDb a přejděte z externího ID na ID seriálu.

Mohu získat skóre z IMDb a Rotten Tomatoes pro seriál?

Ano. Zavolejte GET /3/tv/{series_id}/ratings nebo přidejte append_to_response=ratings. Dostanete skóre z IMDb, Kinopoisk, Metacritic, Rotten Tomatoes a TMDB, každé jako value a votes, nebo null, když skóre není známo.

Jak dlouho se cachují data seriálů?

Detaily seriálu a jejich dílčí zdroje se na edge cachují 6 hodin, takže se právě odvysílaná epizoda může v last_episode_to_air objevit s tímto zpožděním. Seznamy jako on the air se cachují 30 minut.

API detailu seriálu: endpointy kompatibilní s TMDB v3

Získání detailů seriálu

GET /3/tv/{series_id} vrací základní záznam jednoho seriálu: názvy, popis, stav, žánry, televizní sítě, seznam sezón a odkazy na poslední a další epizodu. ID je číselné ID seriálu z TMDB, takže seriál, který ukládáte jako 1396, si ho zde ponechá. ID filmů a ID seriálů jsou oddělené prostory, vždy proto ukládejte vedle čísla i typ média.

Příklad si vyžádá Breaking Bad v angličtině a ve stejném volání přidá věková hodnocení a externí skóre.

curl JavaScript Python PHP Go

bashjspyphpgo

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

Parametry

series_idpathpovinný
Číselné ID seriálu, například 1396.
api_keyqueryjeden ze dvou
Váš klíč. Použijte jej, nebo hlavičku Authorization: Bearer.
languagequery
Tag TMDB, například en-US, uk-UA nebo es-ES. Podporuje se 14 základních jazyků. Výchozí en-US.
append_to_responsequery
Seznam dílčích zdrojů oddělených čárkami, které se sloučí do odpovědi, až 20 hodnot.

Pole odpovědi

Pole	Typ	Poznámky
`id`	integer	ID seriálu.
`name`, `original_name`	string	Lokalizovaný a původní název. Původní japonské nebo korejské názvy zůstávají v `original_name`.
`overview`, `tagline`	string	Lokalizovaný text, prázdný, když překlad neexistuje.
`first_air_date`, `last_air_date`	string nebo null	`YYYY-MM-DD`.
`status`	string	Životní cyklus, viz tabulka níže.
`in_production`	boolean	`true`, dokud se seriál stále natáčí.
`number_of_seasons`, `number_of_episodes`	integer	Součty, tak jak jsou uloženy pro seriál.
`episode_run_time`	array	Typické délky epizod v minutách, může být prázdné.
`seasons`	array	Jeden souhrn na sezónu s `id`, `season_number`, `name`, `overview`, `episode_count`, `air_date`, `poster_path`, `vote_average`.
`last_episode_to_air`, `next_episode_to_air`	object nebo null	Souhrny epizod ve tvaru objektů na stránce sezóny a epizody.
`networks`, `production_companies`	array	`id`, `name`, `logo_path`, `origin_country`.
`production_countries`, `spoken_languages`	array	Země s `iso_3166_1` a `name`. Jazyky s `english_name`, `iso_639_1` a `name`.
`created_by`	array	Tvůrci s `id`, `name`, `profile_path` a `credit_id`. U většiny seriálů prázdné.
`genres`	array	Objekty s `id` a `name`. ID žánrů seriálů se liší od ID filmů.
`origin_country`, `original_language`, `languages`	array, string	Kódy zemí a kódy jazyků.
`homepage`	string	Oficiální web, prázdný, když není znám.
`poster_path`, `backdrop_path`	string nebo null	Připojte k `https://img.amodb.dev/t/p/{size}`. Viz obrázky.
`popularity`	number	Relativní skóre používané seznamem populárních.
`vote_average`, `vote_count`	number, integer	Souhrnné skóre uživatelů.
`adult`	boolean	Vždy `false`. Tituly pro dospělé se nikdy neposkytují.

Příklad odpovědi

GET /3/tv/1396?language=en-US&append_to_response=content_ratings,ratings, s dlouhými poli a texty zkrácenými:

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

Bloky content_ratings a ratings pocházejí z append_to_response. Názvy a popisy uvnitř seasons, last_episode_to_air a next_episode_to_air jsou uloženy pro každý záznam zvlášť a nemusí se řídit language, jak ukazuje hebrejský název epizody výše. Lokalizovaný text sezón a epizod čtěte z endpointu sezóny.

Stav a odkazy na epizody

status říká, v jaké fázi života seriál je, a next_episode_to_air říká, kdy se podívat znovu.

Hodnota `status`	Význam	`next_episode_to_air`
`Returning Series`	Právě se vysílá nebo je mezi sezónami.	Nastaveno, když je datum známo, jinak null.
`Planned`, `In Production`	Ještě není běžným seriálem.	Obvykle null.
`Ended`	Dokončil své vysílání.	Null.
`Canceled`	Zastaven před plánovaným koncem.	Null.

Pokračující seriál mezi sezónami má next_episode_to_air null, čtěte proto null jako „datum není známo“, ne jako „skončil“.

Pole seasons uvádí jeden souhrn na sezónu a sezóna 0 obsahuje speciály. Epizody sezóny načtete voláním endpointu ze stránky sezóny a epizody.

Související endpointy seriálů

Všechny cesty sdílejí základ https://api.amodb.dev/3 a endpointy s lokalizovaným textem přijímají také language.

Metoda a cesta	Vrací	Další parametry
`GET /tv/{series_id}/alternative_titles`	`{id, results}` s `iso_3166_1`, `title`, `type`, často prázdné	žádné
`GET /tv/{series_id}/content_ratings`	Věkové hodnocení podle zemí	žádné
`GET /tv/{series_id}/episode_groups`	Seznam alternativních řazení epizod, například podle DVD nebo dějového oblouku	žádné
`GET /tv/{series_id}/recommendations`	Seznam 20 doporučených seriálů	žádné
`GET /tv/{series_id}/similar`	Seznam 20 podobných seriálů	žádné
`GET /tv/{series_id}/reviews`	`results` je u většiny seriálů prázdné	žádné
`GET /tv/{series_id}/lists`	Veřejné seznamy, které seriál obsahují	`page`
`GET /tv/{series_id}/watch/providers`	Poskytovatelé streamování, půjčování a koupě podle zemí	žádné
`GET /tv/latest`	Nejnovější přidaný záznam seriálu	žádné

Seznamy doporučení a podobných vždy vracejí stránku 1 s 20 položkami. Odpověď lists je stránkovaná přes page, 20 seznamů na stránku. Stránkované seznamy jinde v API přijímají page od 1 do 500.

Věková hodnocení přicházejí jako položky results s iso_3166_1, rating a descriptors, vyberte proto položku, která odpovídá zemi diváka. Poskytovatelé streamování jsou členěni podle kódu země a každá země obsahuje link plus seznamy flatrate, rent a buy s provider_id, provider_name, logo_path a display_priority. ID poskytovatelů pro filtrování pocházejí z číselníků na stránce žánry a číselníky.

Seznam skupin epizod vrací id (řetězec), name, description, type, episode_count, group_count a network. amodb skupiny vypisuje, ale nenabízí endpoint, který by vracel epizody jedné skupiny. Nenabízí ani cesty changes z TMDB.

Sloučení dalších dat do jednoho volání

Dílčí zdroje vypište v append_to_response a každý přijde pod vlastním klíčem. Celé volání se počítá jednou do vašich 20, 40 nebo 120 požadavků za minutu. Funguje až 20 hodnot a neznámé názvy se bez chyby ignorují. U seriálu fungují tyto hodnoty:

Hodnota	Přidává	Podrobnosti
`credits`	Herci a štáb	Obsazení a štáb
`external_ids`	ID jako `imdb_id`, `tvdb_id` a `wikidata_id`	Hledání podle externího ID
`images`, `videos`	Plakáty, pozadí, trailery	Obrázky, Videa
`keywords`, `translations`	Štítky a přeložené texty	Klíčová slova, Překlady
`content_ratings`, `alternative_titles`, `episode_groups`, `lists`, `watch/providers`, `similar`, `recommendations`, `reviews`	Dílčí zdroje z tabulky výše	Tato stránka
`ratings`, `moods`, `soundtracks`, `wikidata`, `showtimes`	Doplňky amodb	Hodnocení, Nálady, Soundtracky, Promítací časy

Chyby

Neúspěšné volání vrací tělo chyby TMDB. Špatné ID dává status_code 34 se zprávou "The resource you requested could not be found."

HTTP	status_code	Kdy
401	7	Klíč chybí nebo je nesprávný.
402	36	Platnost tarifu skončila.
404	34	Seriál s tímto ID neexistuje, titul pro dospělé, nebo cesta, která se nenabízí.
405	37	Zavolali jste metodu pro zápis, například hodnocení seriálu.
429	25	Překročen počet požadavků za minutu. Počkejte tolik sekund, kolik říká `Retry-After`.

Úplný seznam je na stránce chyby a limity podle tarifu na stránce limity požadavků.

Praktické poznámky

Detaily seriálu a všechny výše uvedené dílčí zdroje se cachují 6 hodin. last_episode_to_air kontrolujte nejvýše několikrát denně.
Vyžádejte jazyk, který zobrazujete. Prázdný overview znamená, že překlad neexistuje, pro zálohu proto požádejte znovu s en-US.
Při načítání každé sezóny, jedno volání na sezónu, použijte number_of_seasons jako horní mez smyčky.
Chcete-li seriály vypsat, a ne číst jeden, viz vyhledávání, discover a trendy a seznamy.