API לאוספים
אוסף מקבץ את הסרטים של זיכיון אחד, כמו טרילוגיה או סדרת סרטים ארוכה. GET /3/collection/{collection_id} מחזיר את השם, התקציר, הגרפיקה ומערך parts של סרטים לפי סדר יציאה. סרטים מצביעים חזרה על האוסף שלהם דרך belongs_to_collection, ולכן אפשר לנוע בשני הכיוונים.
קבלת אוסף
GET / מחזיר זיכיון אחד: את השם שלו, תקציר, פוסטר, תמונת רקע ואת המערך parts. כל חלק הוא סיכום של סרט עם השדות הדרושים לכרטיס, ולכן קריאה אחת יכולה לצייר מדף שלם של זיכיון.
הדוגמה טוענת את אוסף 10, סרטי מלחמת הכוכבים, ומדפיסה את הסרטים שלו לפי סדר יציאה.
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. באוספים מסוימים הם לא באנגלית.
שדות התגובה
| שדה | סוג | הערות |
|---|---|---|
id | integer | מזהה האוסף. |
name | string | שם הזיכיון. |
overview | string | תיאור קצר. ריק בחלק מהאוספים. |
poster_path, backdrop_path | string או null | מצרפים ל-https:/. ראו תמונות. |
parts | array | סיכומי סרטים, release_date הישן ביותר ראשון. |
parts[].id | integer | מזהה הסרט. העבירו אותו אל פרטי סרט. |
parts[].title, parts[].original_title | string | כותרת מתורגמת וכותרת מקורית. |
parts[].overview | string | תקציר מתורגם. |
parts[].release_date | string | YYYY-MM-DD, או מחרוזת ריקה לסרט בלי תאריך. חלקים כאלה מופיעים אחרונים. |
parts[].media_type | string | תמיד movie באוסף. |
parts[].genre_ids | array | מזהים מספריים. השמות מגיעים מעמוד ז'אנרים. |
parts[].adult, parts[].video | boolean | adult הוא תמיד false, כי כותרים למבוגרים לא מוגשים. |
parts[].original_ | string | קוד שפה בן שתי אותיות. |
parts[].popularity | number | ציון פופולריות. |
parts[].poster_path, parts[].backdrop_path | string או null | הגרפיקה של הסרט. |
parts[].vote_average, parts[].vote_count | number, integer | ציון משתמשים מצטבר. |
תגובה לדוגמה
מוצגים שניים מתוך תשעת החלקים.
{
"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.
{
"id": 11,
"title": "Star Wars",
"belongs_to_collection": {
"id": 10,
"name": "Star Wars Collection",
"poster_path": "/pWVLFh4OuejTpUaDQbB1C4zoS2p.jpg",
"backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg"
}
}הדוגמה שלמטה עוקבת אחרי הקישור הזה מסרט אל הזיכיון שלו בשתי בקשות.
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 לא מציע את הנתיבים / ו-/, ולכן לאוסף אין רשימת פוסטרים חלופיים ואין שורות לפי שפה. במקום זה הכותרות של החלקים עוקבות אחרי הפרמטר language, והנתיבים שכן מחזירים שורות לפי שפה מכוסים בעמוד תרגומים.
כדי למצוא אוסף לפי שם, השתמשו ב-GET /, שמתואר בעמוד חיפוש. בכל תוצאה יש id, name, overview, poster_path, backdrop_path, original_language, original_name ו-adult.
שגיאות
| HTTP | status_code | מתי |
|---|---|---|
| 401 | 7 | המפתח חסר או שגוי. |
| 402 | 36 | תקופת המסלול הסתיימה. |
| 404 | 34 | אין אוסף עם המזהה הזה, או שהמזהה אינו מספר. |
| 405 | 37 | השתמשתם בשיטת כתיבה בנתיב של אוסף. |
| 429 | 25 | חרגתם מהבקשות שלכם לדקה. המתינו Retry-After שניות. |
את הרשימה המלאה ראו בעמוד שגיאות, ואת מגבלות המסלולים בעמוד מגבלות קצב.
הערות מעשיות
- אוספים מקבצים סרטים בלבד. לסרט יש לכל היותר אובייקט
belongs_to_collectionאחד, ולכן סרט אחד ממופה לזיכיון אחד. - החלקים מגיעים לפי סדר יציאה. סרטים עם תאריך ריק מגיעים אחרונים, ולכן סמנו אותם כעדיין בלי תאריך.
- רשומת האוסף נשמרת בקצה במטמון 6 שעות כמו פרטים אחרים, ולכן עמוד זיכיון יכול להשתמש שוב בתגובה אחת כל כך הרבה זמן.
- חלק נושא רק שדות סיכום. שלפו משך, קרדיטים ודירוגים לכל סרט דרך פרטי סרט כשהמשתמש פותח אותו.
- השתמשו ב-
parts[].idכמפתח של סרט, לא במיקום שלו בזיכיון. סדר ותאריכים מתוקנים עם הזמן. - בדקו ש-
nameבשפת התצוגה שלכם לפני שמציגים אותו. באוספים מסוימים השם בשפה אחרת, ו-languageלא משנה אותו.