API seriale TV

Obține detaliile unui serial TV

GET /3/tv/{series_id} întoarce fișa de bază a unui serial: nume, descriere, stare, genuri, rețele, lista de sezoane și indicatori către ultimul și următorul episod. ID-ul este ID-ul numeric de TV TMDB, deci un serial pe care îl stochezi ca 1396 păstrează acel ID aici. ID-urile de film și cele de TV sunt spații separate, deci stochează mereu tipul de media lângă număr.

Exemplul cere Breaking Bad în engleză și îi atașează în același apel clasificările de conținut și scorurile externe.

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

Parametri

• series_idcaleobligatoriu
  ID numeric de TV, de exemplu 1396.
• api_keyinterogareuna dintre cele două
  Cheia ta. Folosește-o pe aceasta sau antetul Authorization: Bearer.
• languageinterogare
  Etichetă TMDB precum en-US, uk-UA sau es-ES. Sunt servite 14 limbi de bază. Implicit en-US.
• append_to_responseinterogare
  Listă separată prin virgulă de sub-resurse de îmbinat în răspuns, până la 20 de valori.

Câmpurile răspunsului

Exemplu de răspuns

GET /3/tv/1396?language=en-US&append_to_response=content_ratings,ratings, cu array-urile lungi și textul scurtate:

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

Blocurile content_ratings și ratings vin din append_to_response. Numele și descrierile din seasons, last_episode_to_air și next_episode_to_air sunt stocate pe înregistrare și este posibil să nu urmeze language, după cum arată numele de episod în ebraică de mai sus. Citește textul localizat de sezon și de episod de la endpoint-ul de sezon.

Stare și indicatori de episoade

status îți spune în ce fază a vieții se află un serial, iar next_episode_to_air îți spune când să te uiți din nou.

Un serial care revine, aflat între sezoane, are next_episode_to_air null, deci citește null ca „nu se cunoaște nicio dată” și nu ca „încheiat”.

Array-ul seasons listează un rezumat pe sezon, iar sezonul 0 conține episoadele speciale. Ca să citești episoadele unui sezon, apelează endpoint-ul de la sezoane și episoade.

Endpoint-uri înrudite pentru seriale

Toate căile au baza https://api.amodb.dev/3, iar endpoint-urile cu text localizat primesc și language.

Listele de recomandări și de seriale similare întorc mereu pagina 1 cu 20 de elemente. Răspunsul lists este paginat cu page, câte 20 de liste pe pagină. Listele paginate din alte părți ale API-ului primesc page de la 1 la 500.

Clasificările de conținut vin ca intrări results cu iso_3166_1, rating și descriptors, deci alege intrarea care se potrivește cu țara spectatorului. Furnizorii de vizionare sunt indexați după codul de țară, iar fiecare țară conține un link plus liste flatrate, rent și buy cu provider_id, provider_name, logo_path și display_priority. ID-urile de furnizori pentru filtrare vin din listele de referință de la genuri și liste de referință.

Lista grupurilor de episoade întoarce id (un șir), name, description, type, episode_count, group_count și network. amodb listează grupurile, dar nu oferă un endpoint care să întoarcă episoadele unui grup. Nu oferă nici căile TMDB changes.

Îmbină mai multe date într-un singur apel

Listează sub-resursele în append_to_response și fiecare sosește sub propria cheie. Tot apelul se numără o dată din cele 20, 40 sau 120 de cereri pe minut. Funcționează până la 20 de valori, iar numele necunoscute sunt ignorate fără eroare. Aceste valori funcționează la un serial:

Erori

Un apel eșuat întoarce corpul de eroare TMDB. Un ID greșit dă status_code 34 cu mesajul „The resource you requested could not be found.”

Lista completă este la erori, iar limitele pe plan sunt la limite de cereri.

Note practice

• Detaliile serialelor și fiecare sub-resursă de mai sus sunt ținute în cache 6 ore. Interoghează last_episode_to_air cel mult de câteva ori pe zi.
• Cere limba pe care o afișezi. Un overview gol înseamnă că nu există traducere, deci cere din nou cu en-US pentru o variantă de rezervă.
• Folosește number_of_seasons drept limită a buclei când preiei fiecare sezon, câte un apel pe sezon.
• Ca să listezi seriale în loc să citești unul, vezi căutare, descoperire și tendințe și liste.