איך יודעים אם סדרה עדיין משודרת?

קראו את status יחד עם next_episode_to_air. לסדרה במעמד ממשיכה עם next_episode_to_air שאינו null יש פרק מתוזמן. סדרות שהסתיימו או בוטלו מחזירות שם תמיד null, וגם סדרה שבין עונות יכולה.

האם רשומת הסדרה כוללת מזהה IMDb?

לא ברשומת הבסיס, כמו ב-TMDB. הוסיפו append_to_response=external_ids כדי לקבל imdb_id ו-tvdb_id, או קראו לנקודת הקצה find עם מזהה IMDb כדי לעבור ממזהה חיצוני למזהה הסדרה.

אפשר לקבל ציוני IMDb ו-Rotten Tomatoes לסדרה?

כן. קראו ל-GET /3/tv/{series_id}/ratings או הוסיפו append_to_response=ratings. תקבלו ציונים של IMDb, Kinopoisk, Metacritic, Rotten Tomatoes ו-TMDB, כל אחד כ-value ו-votes, או null כשהציון אינו ידוע.

כמה זמן נתוני סדרות נשמרים במטמון?

פרטי סדרה ומשאבי המשנה שלהם נשמרים בקצה במטמון 6 שעות, ולכן פרק שזה עתה שודר יכול להופיע ב-last_episode_to_air בעיכוב הזה. רשימות כמו משודרים כעת נשמרות 30 דקות.

API סדרות טלוויזיה: נקודות קצה לסדרות תואמות TMDB v3

קבלת פרטי סדרת טלוויזיה

GET /3/tv/{series_id} מחזיר את רשומת הליבה של סדרה אחת: שמות, תקציר, סטטוס, ז'אנרים, רשתות, רשימת העונות ומצביעים לפרק האחרון ולפרק הבא. המזהה הוא מזהה הסדרה המספרי של TMDB, ולכן סדרה ששמרתם כ-1396 שומרת את המזהה הזה גם כאן. מזהי סרטים ומזהי סדרות הם מרחבים נפרדים, ולכן תמיד שמרו את סוג המדיה ליד המספר.

הדוגמה מבקשת את Breaking Bad באנגלית ומצרפת את סיווגי הגיל שלה ואת הציונים החיצוניים באותה קריאה.

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

פרמטרים

series_idנתיבחובה
מזהה סדרה מספרי, למשל 1396.
api_keyשאילתהאחד משניים
המפתח שלכם. השתמשו בו או בכותרת Authorization: Bearer.
languageשאילתה
תגית TMDB כמו en-US, uk-UA או es-ES. מוגשות 14 שפות בסיס. ברירת מחדל en-US.
append_to_responseשאילתה
רשימה מופרדת בפסיקים של משאבי משנה למיזוג לתגובה, עד 20 ערכים.

שדות התגובה

שדה	סוג	הערות
`id`	integer	מזהה הסדרה.
`name`, `original_name`	string	הכותרת המתורגמת והמקורית. שמות מקוריים ביפנית או בקוריאנית נשארים ב-`original_name`.
`overview`, `tagline`	string	טקסט מתורגם, ריק כשאין תרגום.
`first_air_date`, `last_air_date`	string או null	`YYYY-MM-DD`.
`status`	string	מחזור החיים, ראו בטבלה למטה.
`in_production`	boolean	`true` כל עוד הסדרה עדיין בהפקה.
`number_of_seasons`, `number_of_episodes`	integer	סכומים, כפי ששמורים לסדרה.
`episode_run_time`	array	אורכי פרק אופייניים בדקות, יכול להיות ריק.
`seasons`	array	סיכום אחד לכל עונה עם `id`, `season_number`, `name`, `overview`, `episode_count`, `air_date`, `poster_path`, `vote_average`.
`last_episode_to_air`, `next_episode_to_air`	object או null	סיכומי פרקים, במבנה של האובייקטים בעמוד עונות ופרקים.
`networks`, `production_companies`	array	`id`, `name`, `logo_path`, `origin_country`.
`production_countries`, `spoken_languages`	array	מדינות עם `iso_3166_1` ו-`name`. שפות עם `english_name`, `iso_639_1` ו-`name`.
`created_by`	array	יוצרים עם `id`, `name`, `profile_path` ו-`credit_id`. ריק ברוב הסדרות.
`genres`	array	אובייקטים עם `id` ו-`name`. מזהי ז'אנרים של סדרות שונים ממזהי סרטים.
`origin_country`, `original_language`, `languages`	array, string	קודי מדינות וקודי שפות.
`homepage`	string	אתר רשמי, ריק כשאינו ידוע.
`poster_path`, `backdrop_path`	string או null	מצרפים ל-`https://img.amodb.dev/t/p/{size}`. ראו תמונות.
`popularity`	number	ציון יחסי שמשמש את הרשימה הפופולרית.
`vote_average`, `vote_count`	number, integer	ציון המשתמשים המצטבר.
`adult`	boolean	תמיד `false`. כותרי תוכן למבוגרים לא מוגשים לעולם.

תגובה לדוגמה

GET /3/tv/1396?language=en-US&append_to_response=content_ratings,ratings, עם מערכים וטקסטים ארוכים מקוצרים:

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

הבלוקים content_ratings ו-ratings מגיעים מ-append_to_response. שמות ותקצירים בתוך seasons, last_episode_to_air ו-next_episode_to_air שמורים לכל רשומה ויכולים לא לעקוב אחרי language, כפי ששם הפרק בעברית למעלה מראה. את טקסט העונות והפרקים המתורגם קראו מנקודת הקצה של העונה.

סטטוס ומצביעי פרקים

הערך status אומר לכם באיזה שלב בחיים הסדרה נמצאת, והערך next_episode_to_air אומר מתי לבדוק שוב.

ערך `status`	משמעות	`next_episode_to_air`
`Returning Series`	משודרת עכשיו או בין עונות.	מוגדר כשתאריך ידוע, אחרת null.
`Planned`, `In Production`	עדיין לא סדרה רגילה.	לרוב null.
`Ended`	סיימה את הרצתה.	null.
`Canceled`	נעצרה לפני סיום מתוכנן.	null.

לסדרה ממשיכה שבין עונות יש next_episode_to_air שהוא null, ולכן קראו null כאל אין תאריך ידוע ולא כאל הסתיימה.

המערך seasons מפרט סיכום אחד לכל עונה, ועונה 0 מחזיקה פרקים מיוחדים. כדי לקרוא את הפרקים של עונה, קראו לנקודת הקצה בעמוד עונות ופרקים.

נקודות קצה קשורות לסדרות

כל הנתיבים חולקים את בסיס הכתובת https://api.amodb.dev/3, ונקודות קצה עם טקסט מתורגם מקבלות גם language.

שיטה ונתיב	מה מוחזר	פרמטרים נוספים
`GET /tv/{series_id}/alternative_titles`	`{id, results}` עם `iso_3166_1`, `title`, `type`, לרוב ריק	אין
`GET /tv/{series_id}/content_ratings`	סיווג גיל לכל מדינה	אין
`GET /tv/{series_id}/episode_groups`	רשימת סדרי פרקים חלופיים, כמו סדר DVD או קשת עלילה	אין
`GET /tv/{series_id}/recommendations`	רשימה של 20 סדרות מומלצות	אין
`GET /tv/{series_id}/similar`	רשימה של 20 סדרות דומות	אין
`GET /tv/{series_id}/reviews`	`results` ריק ברוב הסדרות	אין
`GET /tv/{series_id}/lists`	רשימות ציבוריות שמכילות את הסדרה	`page`
`GET /tv/{series_id}/watch/providers`	ספקי סטרימינג, השכרה ורכישה לכל מדינה	אין
`GET /tv/latest`	רשומת הסדרה החדשה ביותר שנוספה	אין

רשימות ההמלצות והדומות תמיד מחזירות עמוד 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 (מחרוזת), name, description, type, episode_count, group_count ו-network. amodb מפרט את הקבוצות אבל לא מציע נקודת קצה שמחזירה את הפרקים של קבוצה אחת. הוא גם לא מציע את נתיבי changes של TMDB.

מיזוג עוד נתונים לקריאה אחת

פרטו משאבי משנה ב-append_to_response וכל אחד יגיע תחת מפתח משלו. הקריאה כולה נספרת פעם אחת מתוך 20, 40 או 120 הבקשות שלכם לדקה. אפשר עד 20 ערכים, ושמות לא מוכרים מתעלמים מהם בלי שגיאה. הערכים האלה עובדים בסדרה:

ערך	מה נוסף	פרטים
`credits`	שחקנים וצוות	קרדיטים
`external_ids`	מזהים כמו `imdb_id`, `tvdb_id` ו-`wikidata_id`	חיפוש לפי מזהה חיצוני
`images`, `videos`	פוסטרים, תמונות רקע, טריילרים	תמונות, סרטונים וטריילרים
`keywords`, `translations`	תגיות וטקסטים מתורגמים	מילות מפתח, תרגומים
`content_ratings`, `alternative_titles`, `episode_groups`, `lists`, `watch/providers`, `similar`, `recommendations`, `reviews`	משאבי המשנה שבטבלה למעלה	העמוד הזה
`ratings`, `moods`, `soundtracks`, `wikidata`, `showtimes`	תוספות של amodb	דירוגים, מדדי מצב רוח, פסקולים, זמני הקרנות

שגיאות

קריאה שנכשלה מחזירה את גוף השגיאה של TMDB. מזהה שגוי נותן status_code 34 עם ההודעה "The resource you requested could not be found."

HTTP	status_code	מתי
401	7	המפתח חסר או שגוי.
402	36	תקופת המסלול הסתיימה.
404	34	אין סדרה עם המזהה הזה, כותר תוכן למבוגרים, או נתיב שאינו מוצע.
405	37	קראתם לשיטת כתיבה, כמו דירוג סדרה.
429	25	מעל הבקשות שלכם לדקה. המתינו `Retry-After` שניות.

הרשימה המלאה בעמוד שגיאות, והמגבלות לכל מסלול בעמוד מגבלות קצב.

הערות מעשיות

פרטי סדרה וכל משאבי המשנה שלמעלה נשמרים במטמון 6 שעות. אל תסקרו את last_episode_to_air יותר מכמה פעמים ביום.
בקשו את השפה שאתם מציגים. overview ריק אומר שאין תרגום, ולכן בקשו שוב עם en-US כגיבוי.
השתמשו ב-number_of_seasons כגבול הלולאה כשאתם מושכים כל עונה, קריאה אחת לכל עונה.
כדי לרשום סדרות במקום לקרוא אחת, ראו חיפוש, API גילוי ופופולריים ורשימות.