API לסרטים לחיפוש, פרטים ודירוגים

API לסרטים שמדבר TMDB v3 ו-OMDb

amodb הוא API עצמאי לסרטים. הוא מדבר באותו פרוטוקול כמו TMDB v3 ו-OMDb, ולכן לקוח שנכתב לאחד מהם עובד אחרי שמחליפים את כתובת הבסיס ל-https://api.amodb.dev/3 (או ל-https://api.amodb.dev/omdb/ לקריאות בסגנון OMDb). מוצאים סרט עם /search/movie, ואז קוראים אותו עם /movie/{movie_id} ו-append_to_response.

מה מקבלים:

• JSON במבנה של TMDB v3, עם אותם נתיבים ופרמטרי שאילתה.
• כותרות ותקצירים ב-14 שפות, שנבחרות עם language.
• שחקנים, צוות, טריילרים, מילות מפתח, תמונות ותאריכי יציאה דרך append_to_response.
• דירוגים מ-IMDb, Kinopoisk, Metacritic, Rotten Tomatoes ו-TMDB כשהם ידועים.
• פוסטרים מ-https://img.amodb.dev/t/p/{size}/{file}, בלי מפתח.

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

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

1. בחרו מסלול בעמוד תמחור. המסלולים נבדלים רק בקצב: 20, 40 או 120 בקשות לדקה.
2. צרו מפתח בלוח הבקרה של החשבון. מפתח הוא 32 תווים הקסדצימליים באותיות קטנות.
3. קראו לנקודת הקצה עם המפתח בפרמטר api_key או בכותרת Authorization: Bearer. ראו אימות.

בקשה לדוגמה

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

# 1. find the id
curl -s "https://api.amodb.dev/3/search/movie?query=inception&language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"

# 2. read the movie with extras
curl -s "https://api.amodb.dev/3/movie/27205?language=en-US&append_to_response=credits,videos,ratings" \
  -H "Authorization: Bearer $AMODB_KEY"

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

async function get(path, params) {
  const res = await fetch(`${base}${path}?${new URLSearchParams(params)}`, { headers });
  if (res.status === 429) {
    throw new Error(`Over the limit, retry in ${res.headers.get('Retry-After')} s`);
  }
  if (!res.ok) throw new Error(`amodb returned ${res.status}`);
  return res.json();
}

const found = await get('/search/movie', { query: 'inception', language: 'en-US' });
if (!found.results.length) throw new Error('No match');

const movie = await get(`/movie/${found.results[0].id}`, {
  language: 'en-US',
  append_to_response: 'credits,videos,ratings',
});
const director = movie.credits.crew.find((c) => c.job === 'Director');
console.log(movie.title, movie.release_date, movie.runtime, director?.name);
console.log('IMDb', movie.ratings.imdb?.value);

התגובה המקוצרת. נשמרו רק חלק משדות רשומת הסרט, credits קוצר לשחקן אחד ולבמאי, ובלוק videos הושמט.

{
  "genres": [
    {
      "id": 12,
      "name": "Adventure"
    },
    {
      "id": 28,
      "name": "Action"
    },
    {
      "id": 80,
      "name": "Crime"
    }
  ],
  "id": 27205,
  "imdb_id": "tt1375666",
  "poster_path": "/xlaY2zyzMfkhk0HSC5VUwzoZPU1.jpg",
  "release_date": "2010-07-15",
  "runtime": 148,
  "title": "Inception",
  "credits": {
    "cast": [
      {
        "adult": false,
        "gender": 2,
        "id": 6193,
        "known_for_department": "Acting",
        "name": "Leonardo DiCaprio",
        "original_name": "Leonardo DiCaprio",
        "popularity": 9.3213,
        "profile_path": "/wo2hJpn04vbtmh0B9utCFdsQhxM.jpg",
        "character": "Dom Cobb",
        "credit_id": "52fe4534c3a368484e04de03",
        "order": 0
      }
    ],
    "crew": [
      {
        "adult": false,
        "gender": 2,
        "id": 525,
        "known_for_department": "Directing",
        "name": "Christopher Nolan",
        "original_name": "Christopher Nolan",
        "popularity": 8.578,
        "profile_path": "/xuAIuYSmsUzKlUMBFGVZaWsY3DZ.jpg",
        "credit_id": "5e83ac2ee33f830018359a00",
        "department": "Directing",
        "job": "Director"
      }
    ]
  },
  "ratings": {
    "imdb": {
      "value": 8.8,
      "votes": 2877173
    },
    "kinopoisk": {
      "value": 8.7,
      "votes": null
    },
    "metacritic": {
      "value": 74,
      "votes": null
    },
    "rotten_tomatoes": {
      "value": 86,
      "votes": null
    },
    "tmdb": {
      "value": 8.373,
      "votes": 40457
    }
  }
}

דרכים למצוא סרט

בחרו את הקריאה שמתאימה למה שכבר יש בידיכם.

שמרו את שני המזהים. ה-id המספרי הוא המפתח לכל שאר הקריאות, ו-imdb_id מחבר את הנתונים שלכם למערכות אחרות. כללי החיפוש מופיעים בעמוד חיפוש לפי מזהה חיצוני.

שדות ריקים וחיפושים שנכשלו

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

הרשימה המלאה של השגיאות נמצאת בעמוד שגיאות.

הישארות בתוך מגבלת הקצב

חיפוש וקריאת פרטים עולים בקשה אחת כל אחד. ב-20 בקשות לדקה זה עשרה חיפושי כותר בדקה, וב-120 בקשות לדקה זה שישים. פגיעת מטמון בקצה עדיין נספרת, כי בדיקת המפתח ומגבלת הקצב רצות לפני המטמון. החזיקו מטמון משלכם לחיפושים חוזרים, וקראו את X-RateLimit-Remaining כדי לראות כמה נשאר מהדקה. כשמקבלים 429, המתינו Retry-After שניות. המגבלות לפי מסלול מופיעות בעמוד מגבלות קצב.

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

תמחור

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