API серыялаў

Атрыманне дэталяў серыяла

GET /3/tv/{series_id} вяртае асноўны запіс аднаго серыяла: назвы, апісанне, статус, жанры, тэлеканалы, спіс сезонаў і ўказальнікі на апошні і наступны эпізоды. Id той самы лікавы tv id у TMDB, таму серыял, які вы захоўваеце як 1396, захоўвае гэты id і тут. Id фільмаў і id серыялаў гэта асобныя прасторы, таму заўсёды захоўвайце тып медыя побач з лікам.

У прыкладзе запытваецца Breaking Bad па-англійску і ў тым жа выкліку дадаюцца ўзроставыя рэйтынгі і знешнія ацэнкі.

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

Параметры

• series_idшляхабавязковы
  Лікавы id серыяла, напрыклад 1396.
• api_keyзапытадзін з двух
  Ваш ключ. Выкарыстоўвайце яго або загаловак Authorization: Bearer.
• languageзапыт
  Тэг TMDB, напрыклад en-US, uk-UA або es-ES. Падтрымліваюцца 14 базавых моў. Па змаўчанні en-US.
• append_to_responseзапыт
  Спіс падрэсурсаў праз коску, якія трэба далучыць да адказу, да 20 значэнняў.

Палі адказу

Прыклад адказу

GET /3/tv/1396?language=en-US&append_to_response=content_ratings,ratings, доўгія масівы і тэкст скарочаны:

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

Блокі content_ratings і ratings паходзяць з append_to_response. Назвы і апісанні ўнутры seasons, last_episode_to_air і next_episode_to_air захоўваюцца для кожнага запісу асобна і могуць не выконваць language, як паказвае яўрэйская назва эпізода вышэй. Лакалізаваны тэкст сезонаў і эпізодаў чытайце з эндпоінта сезона.

Статус і ўказальнікі на эпізоды

status паказвае, на якім этапе жыцця серыял, а next_episode_to_air падказвае, калі зазірнуць зноў.

У серыяла, які працягваецца, паміж сезонамі next_episode_to_air роўны null, таму чытайце null як «даты няма», а не як «завершаны».

Масіў seasons пералічвае па адным кароткім апісанні на сезон, а сезон 0 змяшчае спецвыпускі. Каб прачытаць эпізоды сезона, выклічце эндпоінт са старонкі сезоны і эпізоды.

Звязаныя эндпоінты серыяла

Усе шляхі маюць агульную аснову https://api.amodb.dev/3, а эндпоінты з лакалізаваным тэкстам таксама прымаюць language.

Спісы recommendations і similar заўсёды вяртаюць старонку 1 з 20 элементамі. Адказ lists падзелены на старонкі праз page, па 20 спісаў на старонку. Іншыя спісы па старонках у API прымаюць page ад 1 да 500.

Узроставыя рэйтынгі прыходзяць як запісы results з iso_3166_1, rating і descriptors, таму абірайце запіс, што адпавядае краіне гледача. Сэрвісы прагляду ідуць па коду краіны, і ў кожнай краіны ёсць link плюс спісы flatrate, rent і buy з provider_id, provider_name, logo_path і display_priority. Id сэрвісаў для фільтрацыі бярыце з даведачных спісаў на старонцы жанры і даведачныя спісы.

Спіс груп эпізодаў вяртае id (радок), name, description, type, episode_count, group_count і network. amodb пералічвае групы, але не прапануе эндпоінт, які вяртае эпізоды адной групы. Ён таксама не прапануе шляхі TMDB changes.

Аб’яднанне большай колькасці даных у адным выкліку

Пералічыце падрэсурсы ў append_to_response, і кожны прыйдзе пад уласным ключом. Увесь выклік лічыцца адзін раз у вашых 20, 40 або 120 запытах у хвіліну. Працуюць да 20 значэнняў, а невядомыя назвы ігнаруюцца без памылкі. Для серыяла працуюць гэтыя значэнні:

Памылкі

Няўдалы выклік вяртае цела памылкі TMDB. Няправільны id дае status_code 34 з паведамленнем «The resource you requested could not be found.»

Поўны спіс ёсць на старонцы памылкі, а ліміты па планах на старонцы ліміты запытаў.

Практычныя заўвагі

• Дэталі серыяла і кожны падрэсурс вышэй кэшуюцца на 6 гадзін. Апытвайце last_episode_to_air не болей за некалькі разоў на дзень.
• Запытвайце тую мову, якую паказваеце. Пусты overview азначае, што перакладу няма, таму для запаснога варыянту паўтарыце запыт з en-US.
• Выкарыстоўвайце number_of_seasons як мяжу цыкла, калі выклікаеце кожны сезон, па выкліку на сезон.
• Каб атрымаць спіс серыялаў, а не адзін, глядзіце пошук, пошук па фільтрах і трэнды і спісы.