API לסדרות טלוויזיה, עונות ופרקים

API לסדרות טלוויזיה עם סטטוס, עונות והפרק הבא

GET /3/tv/{series_id} מחזיר סדרה עם ה-status שלה, networks, רשימת seasons, last_episode_to_air ו-next_episode_to_air. נקודות הקצה של עונות ופרקים מוסיפות תאריכי שידור, משכים ותמונות סצנה. amodb הוא API עצמאי שמדבר בפרוטוקול TMDB v3, ולכן לקוח שנכתב עבור TMDB עובד אחרי שמחליפים את כתובת הבסיס ל-https://api.amodb.dev/3.

מה מקבלים:

• רשומות סדרה עם מספר העונות והפרקים, ותאריכי השידור הראשון והאחרון.
• מחרוזת status ודגל in_production.
• רשתות עם מזהים, לוגואים ומדינת מקור.
• קריאה אחת לכל עונה, שמחזירה את כל הפרקים של העונה.
• רשימות של סדרות שמשודרות היום או בתוך 7 הימים הקרובים.

אילו נתונים מקבלים

רשימות השדות המלאות נמצאות בעמודים סדרות טלוויזיה ועונות ופרקים.

מתחילים בשלושה שלבים

1. פתחו את עמוד תמחור ובחרו את המסלול עם קצב הבקשות שאתם צריכים: 20, 40 או 120 לדקה.
2. צרו מפתח API בלוח הבקרה של החשבון.
3. שלחו GET /3/tv/{series_id} עם Authorization: Bearer YOUR_API_KEY, או הוסיפו את api_key כפרמטר שאילתה.

בקשה לדוגמה

הסקריפט קורא את Breaking Bad (מזהה סדרה 1396), מדפיס את הסטטוס שלה ואת הפרק הבא, ואז מציג את עונה 1. שמרו אותו כ-check.mjs והריצו אותו עם Node 18 ומעלה.

curl -s "https://api.amodb.dev/3/tv/1396?language=en-US&append_to_response=ratings" \
  -H "Authorization: Bearer $AMODB_KEY"

curl -s "https://api.amodb.dev/3/tv/1396/season/1?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"

const base = 'https://api.amodb.dev/3';
const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` };

async function get(path) {
  const res = await fetch(`${base}${path}`, { headers });
  if (!res.ok) throw new Error(`amodb returned ${res.status} for ${path}`);
  return res.json();
}

const show = await get('/tv/1396?language=en-US');
const next = show.next_episode_to_air;
console.log(`${show.name}: ${show.status}, ${show.number_of_seasons} seasons`);
console.log(next
  ? `Next: S${next.season_number}E${next.episode_number} on ${next.air_date}`
  : 'No upcoming episode is scheduled');

const season = await get('/tv/1396/season/1?language=en-US');
for (const ep of season.episodes) {
  console.log(`E${ep.episode_number} ${ep.air_date} ${ep.name}`);
}

תגובת סדרה מקוצרת עבור language=en-US. נשמרו רק חלק מהשדות, וב-seasons מוצגים 2 הפריטים הראשונים מתוך 6. בחלק מהשמות בנתונים האלה אין עקיבה אחרי language: שם עונה 0 הוא בסינית וה-name בתוך last_episode_to_air הוא בעברית.

{
  "first_air_date": "2008-01-20",
  "id": 1396,
  "in_production": false,
  "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,
  "number_of_episodes": 62,
  "number_of_seasons": 5,
  "original_name": "Breaking Bad",
  "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 diagn...",
      "poster_path": "/91EIXdWxmp2mHNRsSuDW3WyDJLj.jpg",
      "season_number": 1,
      "vote_average": 0
    }
  ],
  "status": "Ended"
}

קריאת הסטטוס והפרק הבא

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

השדות בתוך next_episode_to_air ו-last_episode_to_air: air_date, season_number, episode_number, episode_type, id, show_id, name, overview, runtime ו-still_path. מחרוזת status יכולה להיות ריקה גם בכמה כותרים, ולכן הכינו תווית ניטרלית.

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

עונות, פרקים ומה משודר

עונה 0, כשיש כזו לסדרה, מחזיקה פרקים מיוחדים. עונות רגילות מתחילות ב-1.

תוצאות רשימות ו-discover נשמרות במטמון 30 דקות, ולכן בקשה אחת לחצי שעה מספיקה לתג "משודר בקרוב". התאימו את המזהים שחוזרים לסדרות שהמשתמשים שלכם עוקבים אחריהן. פרטי עונות ופרקים מכוסים בעמוד מדריך פרקים.

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

מסך "סדרות שאני עוקב אחריהן" צריך מזהה שמור אחד לכל סדרה ומשימה יומית קטנה.

1. שמרו את ה-id של הסדרה כשמשתמש עוקב אחריה.
2. פעם ביום, קראו ל-/3/tv/{series_id} לכל מזהה במעקב ושמרו את status, next_episode_to_air ו-last_air_date.
3. כש-next_episode_to_air הוא אובייקט, הציגו את air_date כתאריך. הוא לא נושא שעה ביום ואזור זמן, ולכן אל תספרו לאחור עד הדקה.
4. כשהוא null וה-status הוא Returning Series, הציגו "עונה חדשה עדיין לא מתוכננת".
5. שלפו את קריאת העונה רק כשמשתמש פותח את הסדרה, כי היא התגובה הגדולה ביותר.

404 עם status_code 34 אומר שהמזהה לא מוכר, ו-429 אומר שחרגתם מהבקשות לדקה: המתינו Retry-After שניות. עם 200 סדרות במעקב, מעבר יומי אחד הוא 200 בקשות, כעשר דקות ב-20 בקשות לדקה. ראו מגבלות קצב ושגיאות.

איך זה בהשוואה

תמחור

משלמים פעם אחת על 1, 3, 6, 12 או 24 חודשים. תקופות ארוכות יותר מקנות 10, 20, 30 או 40 אחוז הנחה, ושום דבר לא מתחדש אוטומטית. כל מסלול מקבל את כל נתוני הטלוויזיה, וההבדל היחיד הוא 20, 40 או 120 בקשות לדקה. ראו תמחור, צרו מפתח, והקריאה הראשונה לסדרה עולה בקשה אחת.