API מטא-נתונים רב-לשוני לסרטים

קבלת נתוני סרטים ב-14 שפות

GET /3/movie/{movie_id}?language=ru-RU מחזיר את הכותרת, התקציר, הסלוגן ושמות הז'אנרים ברוסית. הפרמטר language מקבל תגיות של TMDB כמו ru-RU או pt-BR ופועל בכל נקודת קצה שמחזירה טקסט. המזהים נשארים זהים בכל שפה, ולכן שורה אחת במסד הנתונים שלכם משרתת את כולן.

מקבלים 14 שפות על מפתח אחד, את ה-original_title של כל סרט, נקודת קצה של תרגומים שמציגה את כל השפות של כותר, ושמות ז'אנרים מתורגמים. הרשימה המלאה נמצאת בעמוד שפות.

14 השפות המוגשות

כל תגית אחרת חוזרת ל-en. יפנית וקוריאנית אינן מוגשות כשפות ממשק. הכותרות המקוריות שלהן עדיין חוזרות ב-original_title לסרטים וב-original_name לסדרות.

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

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

1. בחרו מסלול בעמוד תמחור. מספר השפות לא משתנה לפי המסלול, רק קצב הבקשות.
2. צרו מפתח בלוח הבקרה של החשבון.
3. קראו לכל נקודת קצה עם תגית language, ושלחו את המפתח כ-api_key או ככותרת Bearer.

בקשה לדוגמה

דוגמת ה-bash מדפיסה את הכותרת של Fight Club (מזהה 550) בשלוש שפות. היא משתמשת ב-jq כדי להדפיס שדה אחד. דוגמת ה-PHP מבקשת בלארוסית וחוזרת לאנגלית כשהתקציר ריק.

for lang in en-US ru-RU he-IL; do
  curl -s "https://api.amodb.dev/3/movie/550?language=$lang" \
    -H "Authorization: Bearer $AMODB_KEY" | jq -r '.title'
done

<?php
function amodb(string $path, array $query = []): array
{
    $url = 'https://api.amodb.dev/3' . $path . '?' . http_build_query($query);
    $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");
    }
    return json_decode($body, true);
}

function localizedMovie(int $id, string $lang): array
{
    $movie = amodb("/movie/$id", ['language' => $lang]);
    $movie['text_language'] = $lang;
    if (trim($movie['overview'] ?? '') === '') {
        $fallback = amodb("/movie/$id", ['language' => 'en-US']);
        $movie['overview'] = $fallback['overview'] ?? '';
        $movie['text_language'] = 'en-US';
    }
    return $movie;
}

$movie = localizedMovie(550, 'be-BY');
echo $movie['title'], ' (', $movie['original_title'], ')', PHP_EOL;
echo '[', $movie['text_language'], '] ', $movie['overview'], PHP_EOL;

תגובה עבור language=ru-RU, מקוצרת לכמה שדות. המפתח text_language בדוגמת ה-PHP מתווסף על ידי הקוד שלכם, לא על ידי ה-API.

{
  "genres": [
    {
      "id": 18,
      "name": "драма"
    },
    {
      "id": 53,
      "name": "триллер"
    }
  ],
  "id": 550,
  "original_language": "en",
  "original_title": "Fight Club",
  "overview": "Сотрудник страховой компании страдает хронической бессонницей и отчаянно пытается вырваться из мучительно скучной жизни. Однажды в очередной командировке он...",
  "poster_path": "/66RvLrRJTm4J8l3uHXWF09AICol.jpg",
  "tagline": "«Интриги. Хаос. Мыло»",
  "title": "Бойцовский клуб"
}

גיבוי כשיש שדה ריק

לא לכל כותר יש טקסט בכל שפה. overview יכול לחזור ריק כשאין תרגום, ו-title או tagline יכולים לחזור באנגלית. ה-API לא ממציא טקסט. השתמשו בסדר קבוע כדי שהעמוד תמיד יציג משהו:

1. בקשו את השפה שאתם מציגים.
2. אם שדה ריק, בקשו en-US לאותו מזהה, או קראו את הפריט באנגלית מרשימת התרגומים.
3. אם הכותרת ריקה, הציגו את original_title.
4. שמרו מאיזו שפה הגיע כל שדה, כדי שתוכלו לנסות שוב מאוחר יותר.

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

רשימת כל התרגומים של כותר

GET /3/movie/{movie_id}/translations מחזיר מערך translations, פריט אחד לכל שפה שיש לה נתונים. הרשימה יכולה להיות ארוכה מ-14 השפות המוגשות: ל-Fight Club יש 50 פריטים. השתמשו בה כדי לבנות מחליף שפות, או כדי לשמור את כל הטקסטים של כותר בשורה אחת.

אותה נקודת קצה קיימת לסדרות ולפרקים. פריטי סדרות נושאים data.name ובלי runtime, ופריטי פרקים נושאים רק name ו-overview. עבור עונות מוחזרת רשימה ריקה, ולאנשים ולאוספים אין נקודת קצה של תרגומים. פרטים בעמוד תרגומים. קריאת תרגומים אחת מחליפה עד 14 קריאות פרטים כשרוצים את כל השפות בבת אחת.

פוסטרים וסרטונים לפי שפה

לתמונות ולסרטונים יש תגיות שפה משלהם ב-iso_639_1. בנקודות הקצה של תמונות, העבירו רשימה מופרדת בפסיקים והוסיפו null לפריטים בלי שפה, כמו פוסטרים בלי טקסט. התגובה כוללת את הפריטים התואמים, ולכן דרגו אותם בקוד.

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

עברית וטקסט מימין לשמאל

עברית היא השפה היחידה מימין לשמאל מבין ה-14. טפלו בכך בעמוד, לא בנתונים:

• הגדירו lang="he" ו-dir="rtl" על האלמנט שמחזיק את הטקסט.
• עטפו כותרות לטיניות בתוך טקסט עברי באלמנט <bdi> כדי שסימני פיסוק לא יקפצו לצד הלא נכון.
• השתמשו במאפייני CSS לוגיים כמו margin-inline-start במקום left ו-right.

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

תמחור

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