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 מוסיף קרדיטים, תמונות וסרטונים.
קבלת עונה
GET / מחזיר עונה אחת ואת מערך episodes המלא שלה בתגובה אחת. מספרי עונות מתחילים ב-1, והערך 0 שמור לפרקים מיוחדים. את מזהה הסדרה ואת מספרי העונות קחו מרשומת סדרות טלוויזיה.
הדוגמה קוראת את עונה 1 של Breaking Bad. הקוד מדפיס שורה אחת לכל פרק.
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_number | integer | מזהה העונה ומספרה בתוך הסדרה. |
name, overview | string | טקסט מתורגם, ריק כשאין תרגום. |
air_date | string או null | תאריך הפרק הראשון, YYYY-MM-DD. |
poster_path | string או null | מצרפים ל-https:/. |
vote_average | number | ציון המשתמשים המצטבר של העונה. |
episodes | array | כל הפרקים, עם השדות שברשימה בסעיף הבא. |
תגובה לדוגמה
GET /. בעונה יש 7 פרקים, ולכן episodes קוצר לפריט אחד, והמערכים crew ו-guest_stars של הפריט הזה הושמטו:
{
"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 / מחזיר פרק אחד. תגובת העונה כבר מחזיקה כל פרק עם crew ו-guest_stars, ולכן השתמשו בנקודת הקצה הזו כדי לרענן רשומה אחת בלי לטעון מחדש את העונה. היא מקבלת language ו-append_to_response עם credits, external_ids, images, translations ו-videos. בקשה כמו / עולה בקשה אחת.
| שדה | סוג | הערות |
|---|---|---|
id | integer | מזהה הפרק. |
show_id | integer | מזהה הסדרה. קיים בתגובת העונה ובמצביעים ברשומת הסדרה, לא בתגובה של פרק בודד. |
season_number, episode_number | integer | המיקום בתוך הסדרה. השתמשו בהם כדי לבנות את נתיב הבקשה. |
name, overview | string | טקסט מתורגם. |
air_date | string או null | תאריך בלבד, בלי שעה או אזור זמן. null כשלא מתוזמן. |
episode_type | string | standard בפרקים רגילים. כדי לזהות פרק סיום, השוו את episode_number ל-episode_count של אותה עונה ברשומת הסדרה. |
runtime | integer או null | דקות. |
production_code | string | קוד אולפן, לרוב ריק. |
still_path | string או null | תמונה מהפרק. השתמשו ב-w300 או ב-original מ-https:/. |
vote_average, vote_count | number, integer | ציון המשתמשים המצטבר. |
crew, guest_stars | array | קרדיטים של הפרק הזה, ראו קרדיטים. |
הפרק הבא והאחרון ברשומת הסדרה
נקודת הקצה של הסדרה מחזירה next_episode_to_air ו-last_episode_to_air. כל אחד הוא סיכום פרק עם השדות שלמעלה, בתוספת show_id ובלי crew ו-guest_stars. הפרק הבא הוא null בסדרות שהסתיימו ובסדרות שממשיכות בלי תאריך מאושר. הדוגמה קוראת את South Park, סדרה שממשיכה.
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 / | id, cast ו-crew של העונה |
GET / | id ומערך posters ריק |
GET / | id ומערך results ריק |
GET / | id בתוספת tvdb_id, wikidata_id ומזהים אחרים, כולם null |
GET / | id ומערך translations ריק |
GET .../ | id, cast ריק, crew ו-guest_stars |
GET .../ | id ומערך stills עם התמונה מהפרק |
GET .../ | id ומערך results ריק |
GET .../ | id בתוספת imdb_id, tvdb_id ומזהים אחרים, כולם null |
GET .../ | id ומערך translations עם שם ותקציר לכל שפה |
קרדיטים של עונות ופרקים מכוסים בעמוד קרדיטים, ותמונות מהפרקים בעמוד תמונות. amodb לא מציע את נתיבי changes של TMDB או נקודת קצה לפרקים של קבוצת פרקים אחת.
שגיאות
| HTTP | status_code | מתי |
|---|---|---|
| 401 | 7 | המפתח חסר או שגוי. |
| 402 | 36 | תקופת המסלול הסתיימה. |
| 404 | 34 | הסדרה, העונה או הפרק לא קיימים, למשל עונה 0 בסדרה בלי פרקים מיוחדים, או שהנתיב אינו מוצע. |
| 405 | 37 | קראתם לשיטת כתיבה. |
| 429 | 25 | מעל הבקשות שלכם לדקה. המתינו Retry-After שניות. |
את פורמט גוף השגיאה המלא ראו בעמוד שגיאות, ואת החלונות בעמוד מגבלות קצב.
הערות מעשיות
- עונות ופרקים נשמרים במטמון 6 שעות. קראו מחדש את העונה הנוכחית פעם או פעמיים ביום בזמן ששידור הסדרה נמשך.
- סדרה בת 10 עונות צריכה 10 קריאות עונה. במסלול של 20 בקשות לדקה זה מנצל חצי מהמכסה של דקה אחת, וריצה חוזרת בתוך 6 שעות נענית ממטמון הקצה.
- לפרק שטרם שודר יכולים להיות
air_dateשהוא null,runtimeשהוא null ו-overviewריק. הציגו מקום שמור במקום להיכשל. - תמונות מהפרקים הן פריימים רחבים, לא פוסטרים. בקשו
w300ברשימות ו-originalרק כשצריך תצוגה בגודל מלא.