API עונות ופרקים של סדרות

קראו עונה אחת עם כל הפרקים שלה ב-GET /3/tv/{series_id}/season/{season_number}, או פרק בודד ברמה אחת עמוק יותר. ה-JSON זהה ל-TMDB v3 עם air_date, episode_number, runtime ו-still_path. כל פרק נושא crew ו-guest_stars, עונה 0 מחזיקה פרקים מיוחדים, ו-append_to_response מוסיף קרדיטים, תמונות וסרטונים.

עודכן צפייה כ-Markdown

קבלת עונה

GET /3/tv/{series_id}/season/{season_number} מחזיר עונה אחת ואת מערך episodes המלא שלה בתגובה אחת. מספרי עונות מתחילים ב-1, והערך 0 שמור לפרקים מיוחדים. את מזהה הסדרה ואת מספרי העונות קחו מרשומת סדרות טלוויזיה.

הדוגמה קוראת את עונה 1 של Breaking Bad. הקוד מדפיס שורה אחת לכל פרק.

bashjspyphpgo
curl -sSf "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"
const url = 'https://api.amodb.dev/3/tv/1396/season/1?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 season = await res.json();
for (const ep of season.episodes) {
  console.log(String(ep.episode_number).padStart(2, '0'), ep.name, ep.air_date, `${ep.runtime ?? '?'} min`);
}
import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/tv/1396/season/1",
    params={"language": "en-US"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
season = r.json()
for ep in season["episodes"]:
    print(f"{ep['episode_number']:02d}", ep["name"], ep["air_date"], ep["runtime"] or "?")
<?php
$url = 'https://api.amodb.dev/3/tv/1396/season/1?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");
}
$season = json_decode($body, true);
foreach ($season['episodes'] as $ep) {
    printf("%02d %s %s\n", $ep['episode_number'], $ep['name'], $ep['air_date']);
}
package main

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

type Season struct {
	Name     string `json:"name"`
	Episodes []struct {
		EpisodeNumber int    `json:"episode_number"`
		Name          string `json:"name"`
		AirDate       string `json:"air_date"`
		Runtime       int    `json:"runtime"`
	} `json:"episodes"`
}

func main() {
	req, _ := http.NewRequest("GET", "https://api.amodb.dev/3/tv/1396/season/1?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 s Season
	if err := json.NewDecoder(res.Body).Decode(&s); err != nil {
		panic(err)
	}
	for _, e := range s.Episodes {
		fmt.Printf("%02d %s %s %d min\n", e.EpisodeNumber, e.Name, e.AirDate, e.Runtime)
	}
}

פרמטרים

  • series_idנתיבחובה
    מזהה סדרה מספרי, למשל 1396.
  • season_numberנתיבחובה
    מספר עונה שלם. 0 מחזיר פרקים מיוחדים.
  • api_keyשאילתהאחד משניים
    המפתח שלכם. השתמשו בו או בכותרת Authorization: Bearer.
  • languageשאילתה
    תגית TMDB כמו en-US או fr-FR. מוגשות 14 שפות בסיס. ברירת מחדל en-US.
  • append_to_responseשאילתה
    ערכים ברמת העונה: credits, external_ids, images, videos. שמות אחרים מתעלמים מהם.

שדות התגובה

שדהסוגהערות
id, season_numberintegerמזהה העונה ומספרה בתוך הסדרה.
name, overviewstringטקסט מתורגם, ריק כשאין תרגום.
air_datestring או nullתאריך הפרק הראשון, YYYY-MM-DD.
poster_pathstring או nullמצרפים ל-https://img.amodb.dev/t/p/{size}.
vote_averagenumberציון המשתמשים המצטבר של העונה.
episodesarrayכל הפרקים, עם השדות שברשימה בסעיף הבא.

תגובה לדוגמה

GET /3/tv/1396/season/1?language=en-US. בעונה יש 7 פרקים, ולכן episodes קוצר לפריט אחד, והמערכים crew ו-guest_stars של הפריט הזה הושמטו:

JSON
{
  "air_date": "2008-01-20",
  "episodes": [
    {
      "air_date": "2008-01-20",
      "episode_number": 1,
      "episode_type": "standard",
      "id": 62085,
      "name": "Pilot",
      "overview": "When an unassuming high school chemistry teacher discovers he has a rare form of lung cancer, he decides to...",
      "production_code": "",
      "runtime": 59,
      "season_number": 1,
      "show_id": 1396,
      "still_path": "/ydlY3iPfeOAvu8gVqrxPoMvzNCn.jpg",
      "vote_average": 0,
      "vote_count": 0
    }
  ],
  "name": "Season 1",
  "overview": "High school chemistry teacher Walter White's life is suddenly transformed by a dire medical diagnosis. Stre...",
  "id": 3572,
  "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg",
  "season_number": 1,
  "vote_average": 0
}

כל פרק בתגובת העונה נושא גם מערכי crew ו-guest_stars, במבנה הפריט שמתואר בעמוד קרדיטים. הערך runtime יכול להיות null בפרק שטרם שודר.

קבלת פרק

GET /3/tv/{series_id}/season/{season_number}/episode/{episode_number} מחזיר פרק אחד. תגובת העונה כבר מחזיקה כל פרק עם crew ו-guest_stars, ולכן השתמשו בנקודת הקצה הזו כדי לרענן רשומה אחת בלי לטעון מחדש את העונה. היא מקבלת language ו-append_to_response עם credits, external_ids, images, translations ו-videos. בקשה כמו /3/tv/1396/season/1/episode/1?append_to_response=credits עולה בקשה אחת.

שדהסוגהערות
idintegerמזהה הפרק.
show_idintegerמזהה הסדרה. קיים בתגובת העונה ובמצביעים ברשומת הסדרה, לא בתגובה של פרק בודד.
season_number, episode_numberintegerהמיקום בתוך הסדרה. השתמשו בהם כדי לבנות את נתיב הבקשה.
name, overviewstringטקסט מתורגם.
air_datestring או nullתאריך בלבד, בלי שעה או אזור זמן. null כשלא מתוזמן.
episode_typestringstandard בפרקים רגילים. כדי לזהות פרק סיום, השוו את episode_number ל-episode_count של אותה עונה ברשומת הסדרה.
runtimeinteger או nullדקות.
production_codestringקוד אולפן, לרוב ריק.
still_pathstring או nullתמונה מהפרק. השתמשו ב-w300 או ב-original מ-https://img.amodb.dev/t/p/{size}.
vote_average, vote_countnumber, integerציון המשתמשים המצטבר.
crew, guest_starsarrayקרדיטים של הפרק הזה, ראו קרדיטים.

הפרק הבא והאחרון ברשומת הסדרה

נקודת הקצה של הסדרה מחזירה next_episode_to_air ו-last_episode_to_air. כל אחד הוא סיכום פרק עם השדות שלמעלה, בתוספת show_id ובלי crew ו-guest_stars. הפרק הבא הוא null בסדרות שהסתיימו ובסדרות שממשיכות בלי תאריך מאושר. הדוגמה קוראת את South Park, סדרה שממשיכה.

JavaScript
const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` };
const res = await fetch('https://api.amodb.dev/3/tv/2190', { headers });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const next = (await res.json()).next_episode_to_air;
console.log(next ? `Next: S${next.season_number}E${next.episode_number} on ${next.air_date}` : 'No upcoming episode');

לספירה לאחור, השוו את air_date לתאריך המקומי של הצופה. הערך לא נושא שעה ביום, ולכן הציגו תאריך ולא שעון.

משאבי משנה של עונה ופרק

לנתיבי עונה ופרק יש משאבי משנה משלהם. כמה מהם מחזירים כיום נתונים ריקים.

שיטה ונתיבמה מוחזר
GET /tv/{series_id}/season/{season_number}/creditsid, cast ו-crew של העונה
GET /tv/{series_id}/season/{season_number}/imagesid ומערך posters ריק
GET /tv/{series_id}/season/{season_number}/videosid ומערך results ריק
GET /tv/{series_id}/season/{season_number}/external_idsid בתוספת tvdb_id, wikidata_id ומזהים אחרים, כולם null
GET /tv/{series_id}/season/{season_number}/translationsid ומערך translations ריק
GET .../episode/{episode_number}/creditsid, cast ריק, crew ו-guest_stars
GET .../episode/{episode_number}/imagesid ומערך stills עם התמונה מהפרק
GET .../episode/{episode_number}/videosid ומערך results ריק
GET .../episode/{episode_number}/external_idsid בתוספת imdb_id, tvdb_id ומזהים אחרים, כולם null
GET .../episode/{episode_number}/translationsid ומערך translations עם שם ותקציר לכל שפה

קרדיטים של עונות ופרקים מכוסים בעמוד קרדיטים, ותמונות מהפרקים בעמוד תמונות. amodb לא מציע את נתיבי changes של TMDB או נקודת קצה לפרקים של קבוצת פרקים אחת.

שגיאות

HTTPstatus_codeמתי
4017המפתח חסר או שגוי.
40236תקופת המסלול הסתיימה.
40434הסדרה, העונה או הפרק לא קיימים, למשל עונה 0 בסדרה בלי פרקים מיוחדים, או שהנתיב אינו מוצע.
40537קראתם לשיטת כתיבה.
42925מעל הבקשות שלכם לדקה. המתינו Retry-After שניות.

את פורמט גוף השגיאה המלא ראו בעמוד שגיאות, ואת החלונות בעמוד מגבלות קצב.

הערות מעשיות

  • עונות ופרקים נשמרים במטמון 6 שעות. קראו מחדש את העונה הנוכחית פעם או פעמיים ביום בזמן ששידור הסדרה נמשך.
  • סדרה בת 10 עונות צריכה 10 קריאות עונה. במסלול של 20 בקשות לדקה זה מנצל חצי מהמכסה של דקה אחת, וריצה חוזרת בתוך 6 שעות נענית ממטמון הקצה.
  • לפרק שטרם שודר יכולים להיות air_date שהוא null, runtime שהוא null ו-overview ריק. הציגו מקום שמור במקום להיכשל.
  • תמונות מהפרקים הן פריימים רחבים, לא פוסטרים. בקשו w300 ברשימות ו-original רק כשצריך תצוגה בגודל מלא.