Як атрымаць спіс акцёраў серыяла?

Выклічце GET /3/tv/{series_id}/credits і адсартуйце масіў cast па order. Удзельнікі сезона ахопліваюць адзін сезон, а ўдзельнікі эпізода дадаюць guest_stars. amodb не прапануе зводныя ўдзельнікі серыялаў (aggregate credits).

Як знайсці рэжысёра фільма?

Прачытайце масіў crew і выберыце запіс, дзе job роўна Director. У фільма можа быць некалькі рэжысёраў, таму збірайце ўсе супадзенні, а не спыняйцеся на першым.

Што азначае поле order?

Поле order паказвае месца акцёра ў спісе, 0 азначае першага ў спісе. Сартуйце cast па order, каб спачатку паказваць галоўныя ролі. Запісы crew поля order не маюць.

Адкуль бяруцца запрошаныя зоркі?

Толькі эндпоінт удзельнікаў эпізода вяртае масіў guest_stars побач з crew. Яго масіў cast пусты. Удзельнікі сезона і серыяла не пералічваюць запрошаных зорак асобна.

API ўдзельнікаў: акцёры і група фільма ў фармаце TMDB v3

Атрыманне ўдзельнікаў фільма

GET /3/movie/{movie_id}/credits вяртае два масівы для аднаго фільма: cast для людзей, якія з’яўляюцца ў кадры, і crew для тых, хто працаваў за камерай. Кожны запіс утрымлівае id персоны, таму поўны запіс можна адкрыць на старонцы персоны. Тыя ж даныя ёсць і ў адказе па фільме з append_to_response=credits.

У прыкладзе чытаецца Inception, друкуецца рэжысёр і пяць першых акцёраў са спісу.

curl JavaScript Python PHP Go

bashjspyphpgo

curl -sSf "https://api.amodb.dev/3/movie/27205/credits?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"

const url = 'https://api.amodb.dev/3/movie/27205/credits?language=en-US';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const credits = await res.json();
const director = credits.crew.find((c) => c.job === 'Director');
console.log('Director:', director?.name);
for (const c of [...credits.cast].sort((a, b) => a.order - b.order).slice(0, 5)) {
  console.log(c.order, c.name, 'as', c.character);
}

import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/movie/27205/credits",
    params={"language": "en-US"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
credits = r.json()
director = next((c for c in credits["crew"] if c["job"] == "Director"), None)
print("Director:", director and director["name"])
for c in sorted(credits["cast"], key=lambda c: c["order"])[:5]:
    print(c["order"], c["name"], "as", c["character"])

<?php
$url = 'https://api.amodb.dev/3/movie/27205/credits?language=en-US';
$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");
}
$credits = json_decode($body, true);
usort($credits['cast'], fn ($a, $b) => $a['order'] <=> $b['order']);
foreach (array_slice($credits['cast'], 0, 5) as $c) {
    echo $c['order'], ' ', $c['name'], ' as ', $c['character'], PHP_EOL;
}

package main

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

type Credits struct {
	Cast []struct {
		Order     int    `json:"order"`
		Name      string `json:"name"`
		Character string `json:"character"`
	} `json:"cast"`
	Crew []struct {
		Name string `json:"name"`
		Job  string `json:"job"`
	} `json:"crew"`
}

func main() {
	req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/movie/27205/credits?language=en-US", 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 c Credits
	if err := json.NewDecoder(res.Body).Decode(&c); err != nil {
		panic(err)
	}
	for _, m := range c.Crew {
		if m.Job == "Director" {
			fmt.Println("Director:", m.Name)
		}
	}
	for i, a := range c.Cast {
		if i == 5 {
			break
		}
		fmt.Println(a.Order, a.Name, "as", a.Character)
	}
}

Параметры

movie_idшляхабавязковы
Лікавы id фільма, напрыклад 27205.
api_keyзапытадзін з двух
Ваш ключ. Скарыстайцеся ім або загалоўкам Authorization: Bearer.
languageзапыт
Тэг TMDB, напрыклад en-US або fr-FR. Тэгі па-за межамі 14 базавых моў замяняюцца на en.

Палі адказу

Поле	Дзе ўжываецца	Заўвагі
`id`	верхні ўзровень	Id фільма, серыяла, сезона або эпізода, да якога адносяцца ўдзельнікі.
`cast`, `crew`	верхні ўзровень	Масівы запісаў. Для эпізода дадаецца `guest_stars`.
`id`	кожны запіс	Id персоны. Адкрыйце яго праз персоны.
`name`, `original_name`	кожны запіс	Імя персоны.
`known_for_department`	кожны запіс	Асноўная праца персоны ў цэлым, а не роля ў гэтым тытуле.
`gender`, `popularity`, `adult`	кожны запіс	Сэнс той жа, што ў запісе персоны.
`profile_path`	кожны запіс	Шлях да выявы або null. Дадайце яго да `https://img.amodb.dev/t/p/{size}`.
`credit_id`	кожны запіс	Радок, які ідэнтыфікуе менавіта гэты запіс удзелу.
`character`	cast, запрошаныя зоркі	Назва ролі, у некаторых запісах пустая.
`order`	cast, запрошаныя зоркі	Месца ў спісе, `0` азначае першага.
`department`	crew	Група, напрыклад `Directing`, `Writing`, `Production`, `Camera`, `Editing`, `Sound`, `Art`, `Visual Effects`, `Lighting`, `Costume & Make-Up` або `Crew`.
`job`	crew	Канкрэтная пасада, напрыклад `Director`, `Screenplay` або `Editor`.

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

GET /3/movie/27205/credits?language=en-US. Сёння ў адказе 52 запісы cast і 735 запісаў crew, таму абодва масівы тут скарочаныя да двух:

JSON

{
  "id": 27205,
  "cast": [
    {
      "adult": false,
      "gender": 2,
      "id": 6193,
      "known_for_department": "Acting",
      "name": "Leonardo DiCaprio",
      "original_name": "Leonardo DiCaprio",
      "popularity": 9.3213,
      "profile_path": "/wo2hJpn04vbtmh0B9utCFdsQhxM.jpg",
      "character": "Dom Cobb",
      "credit_id": "52fe4534c3a368484e04de03",
      "order": 0
    },
    {
      "adult": false,
      "gender": 2,
      "id": 24045,
      "known_for_department": "Acting",
      "name": "Joseph Gordon-Levitt",
      "original_name": "Joseph Gordon-Levitt",
      "popularity": 5.6202,
      "profile_path": "/z2FA8js799xqtfiFjBTicFYdfk.jpg",
      "character": "Arthur",
      "credit_id": "52fe4534c3a368484e04de0b",
      "order": 1
    }
  ],
  "crew": [
    {
      "adult": false,
      "gender": 2,
      "id": 1025090,
      "known_for_department": "Crew",
      "name": "Jim Wilkey",
      "original_name": "Jim Wilkey",
      "popularity": 0.9114,
      "profile_path": "/peEdS7ZYHwEeMJAwInJj732AeYs.jpg",
      "credit_id": "6634553bad59b501286dab5f",
      "department": "Crew",
      "job": "Stunt Driver"
    },
    {
      "adult": false,
      "gender": 2,
      "id": 1741194,
      "known_for_department": "Sound",
      "name": "James Thatcher",
      "original_name": "James Thatcher",
      "popularity": 0.6215,
      "profile_path": null,
      "credit_id": "5bcdece8925141613e0216d3",
      "department": "Sound",
      "job": "Musician"
    }
  ]
}

Удзельнікі серыялаў, сезонаў і эпізодаў

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

Метад і шлях	Што вяртае
`GET /tv/{series_id}/credits`	Акцёрскі склад і група серыяла, адзін запіс на кожную персону і ролю.
`GET /tv/{series_id}/season/{season_number}/credits`	Акцёрскі склад і група аднаго сезона.
`GET /tv/{series_id}/season/{season_number}/episode/{episode_number}/credits`	`crew` і `guest_stars` для аднаго эпізода. `cast` вяртаецца пустым масівам.

Тыя ж даныя можна атрымаць праз append_to_response=credits на шляхах серыяла, сезона і эпізода. Форма запісу такая ж, як у ўдзельнікаў фільма вышэй. Запрошаныя зоркі эпізода маюць character і order, а запісы crew маюць department і job.

GET /3/tv/1399/season/1/episode/1/credits?language=en-US, масівы скарочаныя да двух запісаў:

JSON

{
  "id": 63056,
  "cast": [],
  "crew": [
    {
      "department": "Writing",
      "job": "Writer",
      "credit_id": "5256c8a019c2956ff6046e2b",
      "adult": false,
      "gender": 2,
      "id": 9813,
      "known_for_department": "Writing",
      "name": "David Benioff",
      "original_name": "David Benioff",
      "popularity": 2.0354,
      "profile_path": "/xvNN5huL0X8yJ7h3IZfGG4O2zBD.jpg"
    },
    {
      "department": "Editing",
      "job": "Editor",
      "credit_id": "54eef2ab925141795f005d4f",
      "adult": false,
      "gender": 2,
      "id": 18077,
      "known_for_department": "Editing",
      "name": "Oral Norrie Ottey",
      "original_name": "Oral Norrie Ottey",
      "popularity": 0,
      "profile_path": null
    }
  ],
  "guest_stars": [
    {
      "character": "Benjen Stark",
      "credit_id": "5256c8b919c2956ff604836a",
      "order": 61,
      "adult": false,
      "gender": 2,
      "id": 119783,
      "known_for_department": "Acting",
      "name": "Joseph Mawle",
      "original_name": "Joseph Mawle",
      "popularity": 1.4645,
      "profile_path": "/1Ocb9v3h54beGVoJMm4w50UQhLf.jpg"
    },
    {
      "character": "Rickon Stark",
      "credit_id": "566a83bcc3a3683f56003604",
      "order": 80,
      "adult": false,
      "gender": 2,
      "id": 1050248,
      "known_for_department": "Acting",
      "name": "Art Parkinson",
      "original_name": "Art Parkinson",
      "popularity": 1.2594,
      "profile_path": "/ejAKOJME1DsvHECLWdQ7dEtXyyc.jpg"
    }
  ]
}

amodb не прапануе зводныя ўдзельнікі серыялаў і пошук па credit_id. Каб атрымаць акцёрскі склад серыяла, чытайце /tv/{series_id}/credits і сартуйце cast па order.

Як працаваць з акцёрамі і групай у праграме

Задача	Як
Паказаць рэжысёра	Выберыце запісы `crew`, дзе `job` роўна `Director`. У фільма іх можа быць некалькі.
Паказаць галоўных акцёраў	Адсартуйце `cast` па `order` і вазьміце першыя 10.
Згрупаваць здымачную групу	Згрупуйце па `department`. Персона з двума пасадамі трапляе двойчы, таму аб’яднайце запісы па `id` персоны.
Паказаць акцёраў серыяла	Прачытайце ўдзельнікаў серыяла і адсартуйце `cast` па `order`.
Атрымаць спіс усіх аддзелаў і пасад	Скарыстайцеся даведачным спісам са старонкі жанры і даведачныя спісы.

Памылкі

HTTP	status_code	Калі
401	7	Ключ адсутнічае або няправільны.
402	36	Тэрмін дзеяння плана скончыўся.
404	34	Фільма, серыяла, сезона або эпізода не існуе, або шлях не падтрымліваецца.
405	37	Вы выклікалі метад запісу.
429	25	Перавышаны ліміт запытаў у хвіліну. Пачакайце `Retry-After` секунд.

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

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

Удзельнікі кэшуюцца на 6 гадзін, як і дэталі. Новы ўдзельнік акцёрскага складу можа з’явіцца толькі праз гэты час.
У буйной вытворчасці могуць быць сотні запісаў у crew. Абрэжце масівы перад адлюстраваннем.
profile_path роўны null для персон без фота. Выкарыстоўвайце w185 для радкоў спісу і h632 для старонак з дэталямі.
Запісы фільмаў і серыялаў апісаны на старонках фільмы і серыялы. Запісы сезонаў і эпізодаў ёсць на старонцы сезоны і эпізоды.