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

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

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

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

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

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

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

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

1. פתחו את עמוד תמחור ובחרו מסלול. זמני הקרנה כלולים בכל מסלול.
2. צרו מפתח בלוח הבקרה של החשבון.
3. בקשו /3/movie/{movie_id}/showtimes עם קוד country, והעבירו את המפתח ב-api_key או ככותרת Bearer.

בקשה לדוגמה

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

curl -s "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \
  -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.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 מההקרנות שלו.

{
  "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"
    }
  ]
}

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

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

מערך ריק אינו שגיאה ואינו טענה שהסרט חסר בבתי הקולנוע. הוא אומר שלא ידועים נתוני הקרנה. את פורמט הגוף המלא ראו בעמוד שגיאות.

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

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

עמוד אחד של 20 סרטים עולה 21 בקשות. תגובה ליציאה גדולה יכולה להגיע למאות קילובייטים, כי היא כוללת עד 1,500 הקרנות. במסלול של 20 בקשות לדקה זה תקציב של דקה שלמה, ולכן שלפו במשימת רקע והגישו למבקרים מהעותק השמור שלכם. המסלולים של 40 ו-120 בקשות לדקה מתאימים לאותה משימה עם מרווח. את החלון והכותרות ראו בעמוד מגבלות קצב, ואת נקודות הקצה האחרות של רשימות בעמוד טרנדים ורשימות.

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

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

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

תמחור

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