API לאוספים

אוסף מקבץ את הסרטים של זיכיון אחד, כמו טרילוגיה או סדרת סרטים ארוכה. GET /3/collection/{collection_id} מחזיר את השם, התקציר, הגרפיקה ומערך parts של סרטים לפי סדר יציאה. סרטים מצביעים חזרה על האוסף שלהם דרך belongs_to_collection, ולכן אפשר לנוע בשני הכיוונים.

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

קבלת אוסף

GET /3/collection/{collection_id} מחזיר זיכיון אחד: את השם שלו, תקציר, פוסטר, תמונת רקע ואת המערך parts. כל חלק הוא סיכום של סרט עם השדות הדרושים לכרטיס, ולכן קריאה אחת יכולה לצייר מדף שלם של זיכיון.

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

bashjspyphpgo
curl -s "https://api.amodb.dev/3/collection/10?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"
const url = 'https://api.amodb.dev/3/collection/10?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 collection = await res.json();
console.log(collection.name);
for (const p of collection.parts) console.log(p.release_date || 'not dated', p.title);
import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/collection/10",
    params={"language": "en-US"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
collection = r.json()
print(collection["name"])
for p in collection["parts"]:
    print(p.get("release_date") or "not dated", p["title"])
<?php
$url = 'https://api.amodb.dev/3/collection/10?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");
}
$collection = json_decode($body, true);
echo $collection['name'], PHP_EOL;
foreach ($collection['parts'] as $p) {
    echo $p['release_date'] ?: 'not dated', ' ', $p['title'], PHP_EOL;
}
package main

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

type Collection struct {
	Name  string `json:"name"`
	Parts []struct {
		Title       string `json:"title"`
		ReleaseDate string `json:"release_date"`
	} `json:"parts"`
}

func main() {
	url := "https://api.amodb.dev/3/collection/10?language=en-US"
	req, _ := http.NewRequest("GET", url, 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 c Collection
	if err := json.NewDecoder(res.Body).Decode(&c); err != nil {
		panic(err)
	}
	fmt.Println(c.Name)
	for _, p := range c.Parts {
		date := p.ReleaseDate
		if date == "" {
			date = "not dated"
		}
		fmt.Println(date, p.Title)
	}
}

פרמטרים

  • collection_idנתיבחובה
    מזהה אוסף מספרי, למשל 10.
  • api_keyשאילתהאחד משניים
    המפתח שלכם. השתמשו בו או בכותרת Authorization: Bearer.
  • languageשאילתה
    אחת מ-14 השפות המוגשות, למשל en-US או fr-FR. קובע את שפת הכותרת והתקציר של כל חלק. ברירת מחדל en-US.

ה-name וה-overview של האוסף עצמו מגיעים כפי שנשמרו ואינם משתנים לפי language. באוספים מסוימים הם לא באנגלית.

שדות התגובה

שדהסוגהערות
idintegerמזהה האוסף.
namestringשם הזיכיון.
overviewstringתיאור קצר. ריק בחלק מהאוספים.
poster_path, backdrop_pathstring או nullמצרפים ל-https://img.amodb.dev/t/p/{size}. ראו תמונות.
partsarrayסיכומי סרטים, release_date הישן ביותר ראשון.
parts[].idintegerמזהה הסרט. העבירו אותו אל פרטי סרט.
parts[].title, parts[].original_titlestringכותרת מתורגמת וכותרת מקורית.
parts[].overviewstringתקציר מתורגם.
parts[].release_datestringYYYY-MM-DD, או מחרוזת ריקה לסרט בלי תאריך. חלקים כאלה מופיעים אחרונים.
parts[].media_typestringתמיד movie באוסף.
parts[].genre_idsarrayמזהים מספריים. השמות מגיעים מעמוד ז'אנרים.
parts[].adult, parts[].videobooleanadult הוא תמיד false, כי כותרים למבוגרים לא מוגשים.
parts[].original_languagestringקוד שפה בן שתי אותיות.
parts[].popularitynumberציון פופולריות.
parts[].poster_path, parts[].backdrop_pathstring או nullהגרפיקה של הסרט.
parts[].vote_average, parts[].vote_countnumber, integerציון משתמשים מצטבר.

תגובה לדוגמה

מוצגים שניים מתוך תשעת החלקים.

JSON
{
  "id": 10,
  "name": "Star Wars Collection",
  "overview": "An epic space-opera theatrical film series, which depicts the adventures of various cha...",
  "poster_path": "/pWVLFh4OuejTpUaDQbB1C4zoS2p.jpg",
  "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg",
  "parts": [
    {
      "adult": false,
      "backdrop_path": "/zqkmTXzjkAgXmEWLRsY4UpTWCeo.jpg",
      "genre_ids": [12, 28, 878],
      "id": 11,
      "original_language": "en",
      "original_title": "Star Wars",
      "overview": "Princess Leia is captured and held hostage by the evil Imperial forces in their effort...",
      "popularity": 70.481,
      "poster_path": "/fai0rspsNeJCS69wHNjOdWxcI7P.jpg",
      "release_date": "1977-05-25",
      "title": "Star Wars",
      "video": false,
      "vote_average": 8.207,
      "vote_count": 23025,
      "media_type": "movie"
    },
    {
      "adult": false,
      "backdrop_path": "/k9pshruhCpJAdH9RaGJO6jaWQ4X.jpg",
      "genre_ids": [12, 28, 878],
      "id": 1891,
      "original_language": "en",
      "original_title": "The Empire Strikes Back",
      "overview": "The epic saga continues as Luke Skywalker, in hopes of defeating the evil Galactic Empi...",
      "popularity": 29.9034,
      "poster_path": "/nNAeTmF4CtdSgMDplXTDPOpYzsX.jpg",
      "release_date": "1980-05-20",
      "title": "The Empire Strikes Back",
      "video": false,
      "vote_average": 8.393,
      "vote_count": 18990,
      "media_type": "movie"
    }
  ]
}

מחרוזות ארוכות נחתכות עם ... בעמוד הזה. התגובה האמיתית מכילה את הטקסט המלא.

מציאת האוסף של סרט

לעיתים רחוקות מתחילים ממזהה אוסף. מתחילים מסרט, ורשומת פרטי הסרט אומרת לאן הוא שייך. השדה belongs_to_collection הוא אובייקט עם id, name, poster_path ו-backdrop_path. הוא null בסרט שאינו חלק מזיכיון, כמו סרט 550.

JSON
{
  "id": 11,
  "title": "Star Wars",
  "belongs_to_collection": {
    "id": 10,
    "name": "Star Wars Collection",
    "poster_path": "/pWVLFh4OuejTpUaDQbB1C4zoS2p.jpg",
    "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg"
  }
}

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

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

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

const movie = await getJson('/movie/11');
if (movie.belongs_to_collection) {
  const collection = await getJson(`/collection/${movie.belongs_to_collection.id}`);
  console.log(movie.title, 'is one of', collection.parts.length, 'films in', collection.name);
}

גרפיקה וחיפוש

הפוסטר ותמונת הרקע של זיכיון הם השדות poster_path ו-backdrop_path ברשומת האוסף. בנו מהם את כתובת הקובץ כמתואר בעמוד תמונות. amodb לא מציע את הנתיבים /collection/{collection_id}/images ו-/collection/{collection_id}/translations, ולכן לאוסף אין רשימת פוסטרים חלופיים ואין שורות לפי שפה. במקום זה הכותרות של החלקים עוקבות אחרי הפרמטר language, והנתיבים שכן מחזירים שורות לפי שפה מכוסים בעמוד תרגומים.

כדי למצוא אוסף לפי שם, השתמשו ב-GET /3/search/collection?query=matrix, שמתואר בעמוד חיפוש. בכל תוצאה יש id, name, overview, poster_path, backdrop_path, original_language, original_name ו-adult.

שגיאות

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

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

הערות מעשיות

  • אוספים מקבצים סרטים בלבד. לסרט יש לכל היותר אובייקט belongs_to_collection אחד, ולכן סרט אחד ממופה לזיכיון אחד.
  • החלקים מגיעים לפי סדר יציאה. סרטים עם תאריך ריק מגיעים אחרונים, ולכן סמנו אותם כעדיין בלי תאריך.
  • רשומת האוסף נשמרת בקצה במטמון 6 שעות כמו פרטים אחרים, ולכן עמוד זיכיון יכול להשתמש שוב בתגובה אחת כל כך הרבה זמן.
  • חלק נושא רק שדות סיכום. שלפו משך, קרדיטים ודירוגים לכל סרט דרך פרטי סרט כשהמשתמש פותח אותו.
  • השתמשו ב-parts[].id כמפתח של סרט, לא במיקום שלו בזיכיון. סדר ותאריכים מתוקנים עם הזמן.
  • בדקו ש-name בשפת התצוגה שלכם לפני שמציגים אותו. באוספים מסוימים השם בשפה אחרת, ו-language לא משנה אותו.