# API זמני הקרנה בקולנוע

> ה-API לזמני הקרנה בקולנוע הוא GET /3/movie/{movie_id}/showtimes?country=US. הוא מחזיר בתי קולנוע עם כתובת ואזור זמן, ולכל הקרנה שעת התחלה, פורמטים וקישור להזמנה כשהם ידועים. בלי country מקבלים רק ספירות לפי מדינה. הכיסוי משתנה לפי כותר, ומערך results ריק אומר שדבר לא ידוע.

## קבלת זמני הקרנה של סרט

`GET /3/movie/{movie_id}/showtimes?country=US` מחזיר את בתי הקולנוע שמקרינים סרט אחד במדינה אחת, ולכל אחד רשימת הקרנות. `country` הוא קוד של שתי אותיות. בלעדיו `results` נשאר ריק ומקבלים רק ספירות לפי מדינה. הכיסוי משתנה לפי מדינה וכותר, ומערך `results` ריק אומר שלא ידוע דבר עבור הצמד הזה.

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

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

| נקודת קצה                                                   | מה מוחזר                                                                       |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `GET /3/movie/{movie_id}/showtimes`                         | בתי קולנוע והקרנות של סרט אחד ב-`country`, או ספירות לפי מדינה בלעדיו          |
| `GET /3/movie/now_playing`                                  | סרטים שמוצגים כעת בבתי קולנוע, מצומצמים לפי `region`                           |
| `GET /3/movie/{movie_id}` עם `append_to_response=showtimes` | פרטים וזמני הקרנה בבקשה אחת, ראו [זמני הקרנה](https://amodb.dev/he/showtimes/) |

שדות בתגובת זמני ההקרנה:

| שדה                                                                                | סוג                             | משמעות                                                                                        |
| ---------------------------------------------------------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------- |
| `id`                                                                               | integer                         | מזהה הסרט                                                                                     |
| `country`                                                                          | string או null                  | הקוד בן שתי האותיות שביקשתם, `null` כשאף קוד לא היה תקין                                      |
| `results`                                                                          | array                           | פריט אחד לכל בית קולנוע, ריק כשלא ידוע דבר או כש-`country` חסר                                |
| `countries`                                                                        | array                           | ספירות לפי מדינה: `country`, `name`, `venues`, `cities`, `showtimes`, `first_day`, `last_day` |
| `results[].id`, `name`, `city`, `address`                                          | integer, strings                | מזהה בית הקולנוע, שם, עיר וכתובת רחוב                                                         |
| `results[].chain`                                                                  | object או null                  | ה-`key` וה-`name` של רשת בתי הקולנוע                                                          |
| `results[].timezone`                                                               | string או null                  | אזור IANA של בית הקולנוע, למשל `Europe/Moscow`                                                |
| `results[].latitude`, `longitude`                                                  | number או null                  | מיקום, כשהוא ידוע                                                                             |
| `results[].region`, `postal_code`, `phone`, `url`                                  | string או null                  | פרטים נוספים על בית הקולנוע, לעיתים קרובות null                                               |
| `results[].showtimes`                                                              | array                           | ההקרנות בבית הקולנוע הזה                                                                      |
| `showtimes[].date`                                                                 | string                          | יום מקומי כמו `2026-10-18`                                                                    |
| `showtimes[].start`                                                                | string                          | שעת התחלה מקומית כמו `2026-10-18T21:40`, בלי הפרש                                             |
| `showtimes[].auditorium`                                                           | string או null                  | שם או מספר האולם                                                                              |
| `showtimes[].formats`                                                              | array                           | פורמטי הקרנה, למשל `2D`, `IMAX` או `Dolby Atmos`                                              |
| `showtimes[].tags`                                                                 | array                           | תוויות נוספות כמו `Reserved Seating`                                                          |
| `showtimes[].booking_url`                                                          | string או null                  | קישור לרכישת כרטיס, כשהוא ידוע                                                                |
| `showtimes[].sold_out`                                                             | boolean                         | `true` כשהמקור מסמן את ההקרנה כמכורה במלואה                                                   |
| `showtimes[].end`, `audio`, `subtitles`, `language`, `price`, `currency`, `prices` | סוגים שונים, לעיתים קרובות null | מתמלאים רק כשמקור נתוני בית הקולנוע מספק אותם                                                 |

תגובה כוללת לכל היותר 1,500 הקרנות, ממוינות לפי בית קולנוע ואז לפי שעת התחלה.

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

1. פתחו את עמוד [תמחור](https://amodb.dev/he/pricing/) ובחרו מסלול. זמני הקרנה כלולים בכל מסלול.
2. צרו מפתח בלוח הבקרה של החשבון.
3. בקשו `/3/movie/{movie_id}/showtimes` עם קוד `country`, והעבירו את המפתח ב-`api_key` או ככותרת Bearer.

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

דוגמת ה-bash קוראת את זמני ההקרנה של Fight Club (מזהה `550`) ברוסיה, שבה יש ל-amodb הקרנות שלו להיום. דוגמת ה-JS לוקחת את חמשת הסרטים הראשונים ברשימת `now_playing` הרוסית ומדפיסה עד שלוש הקרנות לכל בית קולנוע, או הערה כשלא ידוע דבר.

```bash
curl -s "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \
  -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.ok) throw new Error(`amodb returned ${res.status} for ${path}`);
  return res.json();
}

const country = 'RU';
const playing = await get('/movie/now_playing', { region: country, page: 1 });

for (const movie of playing.results.slice(0, 5)) {
  const { results } = await get(`/movie/${movie.id}/showtimes`, { country });
  if (results.length === 0) {
    console.log(`${movie.title}: no showtimes known`);
    continue;
  }
  for (const cinema of results) {
    const times = cinema.showtimes
      .slice(0, 3)
      .map((s) => `${s.start.slice(5, 10)} ${s.start.slice(11, 16)} ${s.formats.join('/')}`)
      .join(', ');
    console.log(`${movie.title} at ${cinema.name}, ${cinema.city}: ${times}`);
  }
}
```

תגובה מקוצרת עבור `country=RU`: בית הקולנוע הראשון עם 2 מההקרנות שלו.

```json
{
  "id": 550,
  "country": "RU",
  "results": [
    {
      "id": 1114,
      "name": "Мираж Синема НА БОЛЬШОМ",
      "chain": {
        "key": "mirage-ru",
        "name": "Мираж Синема"
      },
      "city": "Санкт-Петербург",
      "region": null,
      "address": "Большой пр. П.С., д. 35А",
      "postal_code": null,
      "country": "RU",
      "timezone": "Europe/Moscow",
      "latitude": null,
      "longitude": null,
      "phone": null,
      "url": "https://www.mirage.ru/spb/cinema/1/",
      "showtimes": [
        {
          "date": "2026-10-18",
          "start": "2026-10-18T21:40",
          "end": null,
          "auditorium": null,
          "formats": [
            "2D"
          ],
          "tags": [],
          "audio": null,
          "subtitles": null,
          "language": null,
          "price": null,
          "currency": null,
          "prices": null,
          "booking_url": "https://www.mirage.ru/ticket_new/aca7b114-d587-4fc5-9df6-28568e8fa9b3/",
          "sold_out": false
        },
        {
          "date": "2026-10-19",
          "start": "2026-10-19T22:20",
          "end": null,
          "auditorium": "Зал №4",
          "formats": [
            "2D"
          ],
          "tags": [],
          "audio": null,
          "subtitles": null,
          "language": null,
          "price": null,
          "currency": null,
          "prices": null,
          "booking_url": "https://www.mirage.ru/ticket_new/0c32e190-890a-4c81-a754-3300fefc4d5e/",
          "sold_out": false
        }
      ]
    }
  ],
  "countries": [
    {
      "country": "RU",
      "name": "Russia",
      "venues": 2,
      "cities": 1,
      "showtimes": 7,
      "first_day": "2026-10-18",
      "last_day": "2026-10-21"
    }
  ]
}
```

## כיסוי ותוצאות ריקות

נתוני בתי קולנוע אינם זמינים לכל מדינה או כותר. תכננו את הממשק שלכם בהתאם.

| מצב                       | מה רואים                                                     | מה לעשות                          |
| ------------------------- | ------------------------------------------------------------ | --------------------------------- |
| הקרנות ידועות             | ב-`results` יש פריט לכל בית קולנוע                           | הציגו את הרשימה                   |
| לא ידוע דבר למדינה ולכותר | `results` הוא מערך ריק, `countries` מציג איפה יש נתונים      | הציגו הודעה ניטרלית, לא טבלה ריקה |
| לא נשלח `country`         | `results` ריק, `country` הוא `null`, ב-`countries` יש ספירות | תנו למשתמש לבחור מתוך `countries` |
| מזהה סרט לא מוכר          | 404 עם `status_code` 34                                      | בדקו את המזהה                     |
| חריגה מהקצב               | 429 עם `status_code` 25                                      | המתינו `Retry-After` שניות        |

מערך ריק אינו שגיאה ואינו טענה שהסרט חסר בבתי הקולנוע. הוא אומר שלא ידועים נתוני הקרנה. את פורמט הגוף המלא ראו בעמוד [שגיאות](https://amodb.dev/he/errors/).

## בניית עמוד רשימות ליציאות עדכניות

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

| שלב | בקשה                                           | הערות                                   |
| --- | ---------------------------------------------- | --------------------------------------- |
| 1   | `GET /3/movie/now_playing?region=US&page=1`    | עד 20 סרטים בעמוד, נשמר במטמון 30 דקות  |
| 2   | `GET /3/movie/{movie_id}/showtimes?country=US` | קריאה אחת לכל סרט, נשמרת במטמון 30 דקות |
| 3   | סינון בקוד שלכם                                | לפי `city`, `formats` או `tags`         |

עמוד אחד של 20 סרטים עולה 21 בקשות. תגובה ליציאה גדולה יכולה להגיע למאות קילובייטים, כי היא כוללת עד 1,500 הקרנות. במסלול של 20 בקשות לדקה זה תקציב של דקה שלמה, ולכן שלפו במשימת רקע והגישו למבקרים מהעותק השמור שלכם. המסלולים של 40 ו-120 בקשות לדקה מתאימים לאותה משימה עם מרווח. את החלון והכותרות ראו בעמוד [מגבלות קצב](https://amodb.dev/he/rate-limits/), ואת נקודות הקצה האחרות של רשימות בעמוד [טרנדים ורשימות](https://amodb.dev/he/trending-lists/).

## שמירה על עותק עדכני

זמני הקרנה משתנים מיום ליום, בניגוד לפרטי סרט. שמרו כל תגובה עם מזהה הסרט, המדינה וזמן השליפה. TTL של 30 דקות עד כמה שעות מתאים לרוב עמודי הרשימות, ואת ההקרנות שכבר התחילו אפשר להסתיר בהשוואת `start` לשעה הנוכחית באזור הזמן `timezone` של בית הקולנוע. מכיוון ש-`start` אינו נושא הפרש, אל תזיזו אותו לאזור הזמן של המבקר.

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

| יכולת           | גירוד אתרי בתי קולנוע       | API למטא-נתונים בלי זמני הקרנה | amodb                                     |
| --------------- | --------------------------- | ------------------------------ | ----------------------------------------- |
| הקמה            | מגרד אחד לכל אתר בית קולנוע | לא קיים                        | נקודת קצה אחת, מבנה JSON אחד              |
| התאמה למזהה סרט | התאמה לפי טקסט הכותרת       | לא קיים                        | מזהה הסרט בנתיב                           |
| כיסוי           | מה שאפשר לגרד               | אין                            | משתנה לפי מדינה וכותר, מערך ריק כשלא ידוע |
| פורמטים והזמנה  | ניתוח תוויות וקישורים       | לא קיים                        | השדות `formats`, `tags` ו-`booking_url`   |
| תחזוקה          | נשבר כשאתר משתנה            | אין                            | מבנה JSON אחד לכל מדינה                   |

## תמחור

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

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

### איך מקבלים זמני הקרנה של סרט?

שלחו GET /3/movie/{movie_id}/showtimes?country=US עם המפתח שלכם. הפרמטר country הוא קוד של שתי אותיות, ו-region עובד ככינוי. התגובה מציגה בתי קולנוע, ולכל אחד מהם ההקרנות שלו עם שעת התחלה, פורמטים, תגיות וקישור להזמנה כשהם ידועים.

### מה אומר מערך results ריק?

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

### אילו מדינות מכוסות?

הכיסוי משתנה לפי מדינה וכותר. כל תגובה כוללת מערך countries עם ספירות של אתרים, ערים והקרנות, עד 60 מדינות, כשהמדינות עם הכי הרבה הקרנות קודמות. קראו אותו לכל סרט במקום לקבוע רשימה בקוד.

### אפשר להציג את הסרטים שמוקרנים עכשיו בבתי הקולנוע?

כן. GET /3/movie/now_playing עם הפרמטר region מציג יציאות עדכניות, ונשמר במטמון 30 דקות. קחו את מזהה הסרט מכל פריט ברשימה ובקשו את זמני ההקרנה שלו עם אותו קוד מדינה.

### באיזה אזור זמן משתמשים ערכי start?

ערך start נראה כמו 2026-10-18T21:40 ואינו נושא הפרש UTC. התייחסו אליו כאל שעון קיר מקומי בבית הקולנוע. לכל אתר יש גם timezone כמו Europe/Moscow. אל תמירו את start לאזור הזמן של הצופה.

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

- [זמני הקרנות בקולנוע](https://amodb.dev/he/showtimes/): API זמני הקרנות שמחזיר בתי קולנוע וזמני הקרנה של סרט במדינה אחת לפי הפרמטר country, או סיכום לפי מדינה. מזגו אותו לפרטים או שלבו אותו עם now_playing.
- [נקודות קצה של מגמות ורשימות](https://amodb.dev/he/trending-lists/): API סרטים פופולריים עם נתיבי TMDB v3: טבלאות יומיות ושבועיות, ורשימות מוקרנים עכשיו, פופולריים, מדורגים וצפויים לסרטים ולסדרות, במטמון 30 דקות.
- [API פרטי סרט](https://amodb.dev/he/movies/): API פרטי סרט עם אותם נתיבים ו-JSON כמו TMDB v3. קבלו סרט לפי מזהה, הוסיפו קרדיטים, דירוגים, מצבי רוח ופסקולים עם append_to_response, ב-14 שפות.
- [מגבלות קצב](https://amodb.dev/he/rate-limits/): amodb מגביל כל מפתח לפי בקשות לדקה בחלון נע של 60 שניות: 20, 40 או 120 בהתאם למסלול שלכם. קראו את כותרות מגבלת הקצב וטפלו ב-429 עם Retry-After.
- [מדריך למתחילים](https://amodb.dev/he/quickstart/): בצעו את הקריאה הראשונה ל-amodb: קבלו מפתח, בקשו פרטי סרט ב-curl, JavaScript, Python, PHP או Go, ואז טענו את הפוסטר מ-img.amodb.dev. פחות מ-2 דקות.

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