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

> amodb הוא API לסרטים בתשלום בכתובת https://api.amodb.dev/3 עם אותם נתיבים ו-JSON כמו TMDB v3. מחפשים כותר עם /search/movie, ואז קוראים את הסרט עם append_to_response כדי לקבל שחקנים, טריילרים ודירוגים בבקשה אחת. התגובות מגיעות ב-14 שפות, החל מ-20 בקשות לדקה, ואין מסלול חינמי.

## 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}`, בלי מפתח.

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

| מה שצריך            | קריאה                        | הערות                                                                                          |
| ------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------- |
| למצוא סרט לפי כותרת | `GET /3/search/movie?query=` | מדורג, עד 20 תוצאות בעמוד, מטמון קצה 10 דקות. ראו [חיפוש](https://amodb.dev/he/search/).       |
| רשומת הליבה         | `GET /3/movie/{movie_id}`    | כותרות, תקציר, משך, ז'אנרים, תאריך יציאה. ראו [סרטים](https://amodb.dev/he/movies/).           |
| שחקנים וצוות        | `append_to_response=credits` | השדות מתוארים בעמוד [קרדיטים](https://amodb.dev/he/credits/).                                  |
| טריילרים            | `append_to_response=videos`  | מחזיר את המערך `results` עם `key`, `site` ו-`type`.                                            |
| ציונים              | `append_to_response=ratings` | חמישה מקורות, כל אחד `{ value, votes }` או null. ראו [דירוגים](https://amodb.dev/he/ratings/). |
| תשובה בסגנון OMDb   | `GET /omdb/?t=Inception`     | אותם שדות גוף כמו ב-OMDb. ראו [נקודת הקצה OMDb](https://amodb.dev/he/omdb-endpoint/).          |

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

1. בחרו מסלול בעמוד [תמחור](https://amodb.dev/he/pricing/). המסלולים נבדלים רק בקצב: 20, 40 או 120 בקשות לדקה.
2. צרו מפתח בלוח הבקרה של החשבון. מפתח הוא 32 תווים הקסדצימליים באותיות קטנות.
3. קראו לנקודת הקצה עם המפתח בפרמטר `api_key` או בכותרת `Authorization: Bearer`. ראו [אימות](https://amodb.dev/he/authentication/).

## בקשה לדוגמה

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

```bash
# 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"
```

```js
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` הושמט.

```json
{
  "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
    }
  }
}
```

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

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

| מתחילים עם                | קריאה                                           | תוצאה                                                          |
| ------------------------- | ----------------------------------------------- | -------------------------------------------------------------- |
| כותרת שמשתמש הקליד        | `GET /3/search/movie?query=`                    | מערך `results` עם `id`, `title`, `release_date`, `poster_path` |
| מזהה IMDb כמו `tt0133093` | `GET /3/find/tt0133093?external_source=imdb_id` | מערך `movie_results`                                           |
| מזהה סרט מספרי כמו `603`  | `GET /3/movie/603`                              | הרשומה המלאה                                                   |
| לקוח OMDb קיים            | `GET /omdb/?i=tt0133093`                        | גוף OMDb עם `Title`, `Year`, `Ratings`                         |

שמרו את שני המזהים. ה-`id` המספרי הוא המפתח לכל שאר הקריאות, ו-`imdb_id` מחבר את הנתונים שלכם למערכות אחרות. כללי החיפוש מופיעים בעמוד [חיפוש לפי מזהה חיצוני](https://amodb.dev/he/find-by-external-id/).

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

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

| מקרה             | מה רואים                | מה לעשות                       |
| ---------------- | ----------------------- | ------------------------------ |
| אין תוצאה בחיפוש | 200 ו-`"results": []`   | הציגו "אין התאמה", אל תנסו שוב |
| מזהה סרט לא מוכר | 404 עם `status_code` 34 | הסירו את המזהה מהרשימה שלכם    |
| מפתח חסר או שגוי | 401 עם `status_code` 7  | עצרו ותקנו את המפתח            |
| `overview` ריק   | מחרוזת ריקה             | בקשו שוב עם `language=en-US`   |
| ציון לא ידוע     | `null` בתוך `ratings`   | הסתירו את התג                  |
| אין תאריך יציאה  | `release_date` ריק      | מיינו את הכותר אחרון           |

הרשימה המלאה של השגיאות נמצאת בעמוד [שגיאות](https://amodb.dev/he/errors/).

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

חיפוש וקריאת פרטים עולים בקשה אחת כל אחד. ב-20 בקשות לדקה זה עשרה חיפושי כותר בדקה, וב-120 בקשות לדקה זה שישים. פגיעת מטמון בקצה עדיין נספרת, כי בדיקת המפתח ומגבלת הקצב רצות לפני המטמון. החזיקו מטמון משלכם לחיפושים חוזרים, וקראו את `X-RateLimit-Remaining` כדי לראות כמה נשאר מהדקה. כשמקבלים 429, המתינו `Retry-After` שניות. המגבלות לפי מסלול מופיעות בעמוד [מגבלות קצב](https://amodb.dev/he/rate-limits/).

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

| יכולת                             | גירוד דפים בעצמכם         | API למטא-נתונים עם מסלול חינמי       | amodb                                         |
| --------------------------------- | ------------------------- | ------------------------------------ | --------------------------------------------- |
| פורמט תגובה                       | HTML שצריך לנתח           | JSON                                 | JSON במבנה של TMDB v3                         |
| יציבות הסכמה                      | נשבר כשהמבנה של הדף משתנה | נקבעת על ידי הספק                    | נתיבים ושדות קבועים, יכולים להופיע שדות חדשים |
| תנאי גישה                         | חלים התנאים של כל אתר     | מסלול חינמי עם תנאי שימוש, בדקו אותם | בתשלום, תשלום מראש, בלי מסלול חינמי           |
| מגבלת קצב                         | שום דבר שאפשר לסמוך עליו  | נקבעת על ידי הספק                    | 20, 40 או 120 בקשות לדקה לכל מפתח             |
| דירוגים מכמה מקורות               | מגרד אחד לכל אתר          | משתנה, ראו במסמכים                   | `ratings` באותה קריאה, null כשלא ידוע         |
| שפות                              | מה שכל דף מציע            | משתנה                                | 14, נבחרות עם `language`                      |
| שימוש חוזר בלקוחות TMDB v3 ו-OMDb | לא                        | רק אם הוא משתמש באותו פרוטוקול       | כן, מחליפים כתובת בסיס                        |

## תמחור

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

## שאלות ותשובות

### האם ה-API לסרטים תואם ל-TMDB?

כן, בנקודות הקצה לקריאה שאפליקציית סרטים צריכה. נתיבים, פרמטרי שאילתה ו-JSON זהים ל-TMDB v3 בכתובת https://api.amodb.dev/3, ולכן מחליפים את כתובת הבסיס ומשתמשים במפתח amodb. שיטות כתיבה לחשבון, להתחברות, לדירוג ולרשימות מחזירות 405 עם status_code 37. פידים של שינויים, aggregate_credits ושליפת קרדיט או ביקורת בודדים מחזירים 404.

### אפשר לחפש סרט לפי מזהה IMDb?

כן. קראו ל-/3/find/tt0133093?external_source=imdb_id וקראו את movie_results, או השתמשו בנקודת הקצה בסגנון OMDb ב-/omdb/?i=tt0133093. שתיהן מקבלות את אותו מפתח כמו קריאות בסגנון TMDB.

### כמה בקשות דרוש עמוד סרט אחד?

שתיים לכל היותר: חיפוש אחד כדי לקבל את המזהה, ואז קריאת /movie/{id} אחת עם append_to_response=credits,videos,ratings. אם המזהה כבר שמור אצלכם, בקשה אחת מספיקה.

### באילו שפות ה-API לסרטים מחזיר תגובות?

ארבע עשרה: אנגלית, רוסית, אוקראינית, בלארוסית, סינית, פורטוגזית, בולגרית, עברית, צ'כית, רומנית, צרפתית, פולנית, איטלקית וספרדית. העבירו תגית של TMDB כמו pt-BR ב-language. כל תגית אחרת חוזרת לאנגלית.

### יש מסלול חינמי או תקופת ניסיון?

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

## עמודים קשורים

- [API פרטי סרט](https://amodb.dev/he/movies/): API פרטי סרט עם אותם נתיבים ו-JSON כמו TMDB v3. קבלו סרט לפי מזהה, הוסיפו קרדיטים, דירוגים, מצבי רוח ופסקולים עם append_to_response, ב-14 שפות.
- [API חיפוש](https://amodb.dev/he/search/): API חיפוש עם אותם נתיבים ו-JSON כמו TMDB v3. מצאו סרטים, סדרות, אנשים, אוספים, חברות ומילות מפתח לפי טקסט, עם סינון לפי שנה ועימוד של 20 תוצאות בעמוד.
- [דירוגי סרטים וסדרות](https://amodb.dev/he/ratings/): API דירוגי סרטים וסדרות שמחזיר ציוני IMDb, Kinopoisk, Metacritic, Rotten Tomatoes ו-TMDB לכותר בקריאה אחת, עם value ו-votes ו-null לכל מקור שאינו ידוע.
- [חיפוש לפי מזהה חיצוני](https://amodb.dev/he/find-by-external-id/): חפשו סרט, סדרה או אדם לפי מזהה IMDb, TVDB, Wikidata או Kinopoisk עם נקודת הקצה find של TMDB v3, וקראו מזהים חיצוניים ועובדות Wikidata על כל כותר.
- [מדריך למתחילים](https://amodb.dev/he/quickstart/): בצעו את הקריאה הראשונה ל-amodb: קבלו מפתח, בקשו פרטי סרט ב-curl, JavaScript, Python, PHP או Go, ואז טענו את הפוסטר מ-img.amodb.dev. פחות מ-2 דקות.
- [חלופה ל-TMDB API](https://amodb.dev/he/tmdb-api-alternative/): מחפשים חלופה ל-TMDB API? בדקו תנאים, מגבלות, שפות ודירוגים, ועברו ל-API בתשלום ששומר את רוב נתיבי הקריאה וה-JSON של TMDB v3. ראו את הפערים לפני המעבר.

עודכן: 2026-10-18. Source: https://amodb.dev/he/movie-api/