# זמני הקרנות בקולנוע > GET /3/movie/{movie_id}/showtimes?country=RU מחזיר את בתי הקולנוע שמקרינים סרט במדינה אחת, עם זמני הקרנה מתוארכים בכל אחד. בלי country הוא מחזיר רק ספירות לפי מדינה ברשימה countries. הכיסוי משתנה לפי מדינה וכותר, ומערך results ריק אומר שלא ידוע דבר על הצמד הזה. ## נקודת קצה `GET /3/movie/{movie_id}/showtimes` ```bash curl "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \ -H "Authorization: Bearer $AMODB_KEY" ``` תגובה: ```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-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 }, { "date": "2026-10-20", "start": "2026-10-20T21: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/7f18e423-4a40-40f3-b68f-8664f4e3fa75/", "sold_out": false }, { "date": "2026-10-21", "start": "2026-10-21T21: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/5ad6b82b-82b3-4ea6-9e65-79388d71b230/", "sold_out": false } ] }, { "id": 1115, "name": "Мираж Синема ПИК", "chain": { "key": "mirage-ru", "name": "Мираж Синема" }, "city": "Санкт-Петербург", "region": null, "address": "ул. Ефимова, д.2", "postal_code": null, "country": "RU", "timezone": "Europe/Moscow", "latitude": null, "longitude": null, "phone": null, "url": "https://www.mirage.ru/spb/cinema/27/", "showtimes": [ { "date": "2026-10-19", "start": "2026-10-19T20:10", "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/1d143ca6-1bbe-48ee-954a-063b6088a32a/", "sold_out": false }, { "date": "2026-10-20", "start": "2026-10-20T20:10", "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/8b2e0f6a-5b62-41eb-a398-1b709539f03d/", "sold_out": false }, { "date": "2026-10-21", "start": "2026-10-21T20:10", "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/3723875b-a7df-426f-968a-4bdaa1a8bdd7/", "sold_out": false } ] } ], "countries": [ { "country": "RU", "name": "Russia", "venues": 2, "cities": 1, "showtimes": 6, "first_day": "2026-10-19", "last_day": "2026-10-21" } ] } ``` ## קבלת זמני הקרנה של סרט `GET /3/movie/{movie_id}/showtimes?country=RU` מחזיר את בתי הקולנוע שמקרינים סרט במדינה אחת, עם זמני ההקרנה המתוארכים בכל אחד. הפרמטר `country` מקבל קוד של שתי אותיות, באותיות גדולות או קטנות. הכיסוי משתנה לפי מדינה וכותר, ולכן הנתונים קיימים איפה שהם ידועים וחסרים איפה שלא. מוחזרים רק ימים מהיום והלאה. הדוגמה מבקשת את Fight Club ברוסיה ומטפלת בתשובה ריקה. ```bash curl -sf "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const url = 'https://api.amodb.dev/3/movie/550/showtimes?country=RU'; const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const data = await res.json(); if (data.results.length === 0) console.log('no showtimes known'); for (const venue of data.results) { for (const s of venue.showtimes) { console.log(venue.name, venue.city, s.start, s.formats.join(','), s.booking_url); } } ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/movie/550/showtimes", params={"country": "RU"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() results = r.json()["results"] if not results: print("no showtimes known") for venue in results: for s in venue["showtimes"]: print(venue["name"], venue["city"], s["start"], ",".join(s["formats"])) ``` ```php 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"); } $results = json_decode($body, true)['results']; if (!$results) { echo 'no showtimes known', PHP_EOL; } foreach ($results as $venue) { foreach ($venue['showtimes'] as $s) { echo $venue['name'], ' ', $s['start'], ' ', implode(',', $s['formats']), PHP_EOL; } } ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" "strings" "time" ) type Venue struct { Name string `json:"name"` City string `json:"city"` Showtimes []struct { Start string `json:"start"` Formats []string `json:"formats"` BookingURL string `json:"booking_url"` } `json:"showtimes"` } func main() { url := "https://api.amodb.dev/3/movie/550/showtimes?country=RU" req, _ := http.NewRequest("GET", url, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY")) client := &http.Client{Timeout: 10 * time.Second} res, err := client.Do(req) if err != nil { panic(err) } defer res.Body.Close() if res.StatusCode != http.StatusOK { panic(res.Status) } var body struct { Results []Venue `json:"results"` } if err := json.NewDecoder(res.Body).Decode(&body); err != nil { panic(err) } if len(body.Results) == 0 { fmt.Println("no showtimes known") } for _, v := range body.Results { for _, s := range v.Showtimes { fmt.Println(v.Name, v.City, s.Start, strings.Join(s.Formats, ",")) } } } ``` ### פרמטרים | פרמטר | מיקום | חובה | תיאור | | ---------- | ------ | ---------- | -------------------------------------------------------------------------------------------- | | `movie_id` | נתיב | כן | מזהה סרט מספרי, למשל `550`. | | `country` | שאילתה | לא | קוד מדינה של שתי אותיות, כמו `RU`. בלעדיו מקבלים רק את הסיכום לפי מדינה. `region` הוא כינוי. | | `api_key` | שאילתה | אחד משניים | המפתח שלכם. השתמשו בו או בכותרת `Authorization: Bearer`. | ### שדות התגובה | שדה | סוג | הערות | | ------------------------------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | | `id` | integer | מזהה הסרט. | | `country` | string או null | הקוד באותיות גדולות שביקשתם, או `null` כש-`country` חסר או שאינו בן שתי אותיות. | | `results` | array | אובייקט אחד לכל בית קולנוע, ממוין לפי בית הקולנוע. ריק כשלא ידוע דבר או שלא נשלחה מדינה. לכל היותר 1500 הקרנות בסך הכול. | | `results[].id` | integer | מזהה בית הקולנוע. | | `results[].name` | string | שם בית הקולנוע. | | `results[].chain` | object | `key` הוא מפתח הרשת, ו-`name` הוא שם הרשת או `null`. | | `results[].city` | string או null | עיר. | | `results[].region` | string או null | אזור. | | `results[].address` | string או null | כתובת רחוב. | | `results[].postal_code` | string או null | מיקוד. | | `results[].country` | string | קוד המדינה של בית הקולנוע. | | `results[].timezone` | string או null | אזור זמן של IANA כמו `Europe/Moscow`. | | `results[].latitude`, `results[].longitude` | number או null | מיקום בית הקולנוע. | | `results[].phone` | string או null | מספר טלפון. | | `results[].url` | string או null | עמוד בית הקולנוע. | | `results[].showtimes` | array | הקרנות באותו בית קולנוע, ממוינות לפי שעת התחלה. | | `results[].showtimes[].date` | string | היום בצורה `2026-10-18`. | | `results[].showtimes[].start` | string | התחלה בשעה המקומית של בית הקולנוע, כמו `2026-10-18T21:40`, בלי הפרש UTC. | | `results[].showtimes[].end` | string או null | סיום בשעה המקומית של בית הקולנוע. | | `results[].showtimes[].auditorium` | string או null | שם האולם. | | `results[].showtimes[].formats` | array of strings | פורמטים כמו `2D`. | | `results[].showtimes[].tags` | array of strings | תוויות נוספות. לרוב ריק. | | `results[].showtimes[].audio`, `subtitles`, `language` | string או null | פרטי שמע, כתוביות ושפה כשהם ידועים. | | `results[].showtimes[].price` | number או null | מחיר כרטיס. | | `results[].showtimes[].currency` | string או null | המטבע של `price`. | | `results[].showtimes[].prices` | any או null | פרטי מחיר כשלבית קולנוע יש כמה מחירים. | | `results[].showtimes[].booking_url` | string או null | קישור להזמנת מקום. | | `results[].showtimes[].sold_out` | boolean | `true` כשההקרנה אזלה. | | `countries` | array | סיכום לפי מדינה, ראו בהמשך. | קראו את המפתחות שאתם משתמשים בהם לפי שם ודלגו על מפתחות נוספים בתוך אובייקט של בית קולנוע או הקרנה. הרבה שדות הם `null` כיום, כי לא כל בית קולנוע שולח אותם. ### תגובה לדוגמה ```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" } ] } ``` הרשימה קוצרה לבית קולנוע אחד מתוך שניים ולשתי הקרנות מתוך ארבע. הקרנות קיימות רק לימים שלא עברו, ולכן התשובה הזו משתנה בכל יום. ## קבלת הסיכום לפי מדינה השמיטו את `country` והתגובה תכיל ספירות בלבד. המערך `results` נשאר ריק ו-`country` הוא `null`. המערך `countries` מונה עד 60 מדינות שעדיין יש בהן הקרנה, ראשונה המדינה עם הכי הרבה הקרנות. השתמשו בו כדי לדעת איפה כותר מוקרן לפני שמבקשים בתי קולנוע. ```bash curl -sf "https://api.amodb.dev/3/movie/550/showtimes" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```json { "id": 550, "country": null, "results": [], "countries": [ { "country": "RU", "name": "Russia", "venues": 2, "cities": 1, "showtimes": 7, "first_day": "2026-10-18", "last_day": "2026-10-21" } ] } ``` | שדה | סוג | הערות | | ----------------------------------------------- | ------- | ------------------------------------------------ | | `countries[].country` | string | קוד של שתי אותיות, מוכן לשימוש כפרמטר `country`. | | `countries[].name` | string | שם המדינה באנגלית. | | `countries[].venues` | integer | בתי קולנוע עם הקרנה. | | `countries[].cities` | integer | ערים עם הקרנה. | | `countries[].showtimes` | integer | הקרנות מהיום והלאה. | | `countries[].first_day`, `countries[].last_day` | string | היום הראשון והאחרון עם הקרנה. | קוד מדינה בלי נתונים, כמו `country=US` לסרט הזה, מחזיר `country` שהוא `US`, `results` ריק ואותה רשימת `countries`. כותר בלי הקרנות בשום מקום, כמו הסדרה 1396, מחזיר `"countries": []`. ## הוספת זמני הקרנה לקריאת פרטים `append_to_response=showtimes` ממזג את אותו בלוק לתגובת פרטים תחת המפתח `showtimes`. שלחו את קוד `country` באותה בקשה. הבלוק שומר על המפתחות `id`, `country`, `results` ו-`countries` שלו. | בקשה | תוצאה | | -------------------------------------------------------------- | --------------------------------------- | | `/3/movie/550?append_to_response=showtimes&country=RU` | רשומת הסרט ובלוק `showtimes` עבור רוסיה | | `/3/movie/550?append_to_response=credits,showtimes&country=RU` | מוסיף קרדיטים לאותה קריאה | זו נספרת כבקשה אחת, ולכן עמוד סרט שמציג שחקנים והקרנות צריך קריאה אחת. אותה נקודת קצה קיימת לסדרות בתור `GET /3/tv/{tv_id}/showtimes`. ## שילוב עם now_playing ו-region רשימת הסרטים שמוקרנים עכשיו נותנת לכם כותרים. נקודת הקצה של זמני ההקרנה נותנת לכם הקרנות של כותר אחד. חברו ביניהם בקוד שלכם. | שלב | בקשה | תוצאה | | --- | ------------------------------------------------- | -------------------------------------- | | 1 | `GET /3/movie/now_playing?region=RU&page=1` | עד 20 סרטים בעמוד, נשמר במטמון 30 דקות | | 2 | `GET /3/movie/{id}/showtimes?country=RU` לכל מזהה | בתי קולנוע וזמנים, איפה שידוע | הלולאה שלמטה מנסה שוב פעם או פעמיים כשמגיעים לגבול המסלול, וממתינה את מספר השניות שב-`Retry-After`. ```js const base = 'https://api.amodb.dev/3'; const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` }; async function get(path, retries = 2) { const res = await fetch(base + path, { headers }); if (res.status === 429 && retries > 0) { const wait = Number(res.headers.get('Retry-After') ?? 60); await new Promise((resolve) => setTimeout(resolve, wait * 1000)); return get(path, retries - 1); } if (!res.ok) throw new Error(`amodb returned ${res.status} for ${path}`); return res.json(); } const playing = await get('/movie/now_playing?region=RU&page=1'); for (const movie of playing.results) { const data = await get(`/movie/${movie.id}/showtimes?country=RU`); if (data.results.length > 0) console.log(movie.title, data.results.length, 'venues'); } ``` עמוד של 20 כותרים הוא 20 בקשות זמני הקרנה. במסלול של 20 בקשות לדקה זה ממצה את כל החלון, ולכן שמרו את התוצאה במטמון בצד שלכם. את פרמטרי הרשימות ראו בעמוד [פופולריים ורשימות](https://amodb.dev/he/trending-lists/). ## שגיאות גוף השגיאה עוקב אחרי TMDB: `success`, `status_code` ו-`status_message`. מפתח שגוי נותן `status_code` 7. | HTTP | status_code | מתי | | ---- | ----------- | ------------------------------------------------- | | 401 | 7 | המפתח חסר או שגוי. | | 402 | 36 | תקופת המסלול הסתיימה. | | 404 | 34 | אין סרט עם המזהה הזה. | | 429 | 25 | מעל הבקשות שלכם לדקה. המתינו `Retry-After` שניות. | היעדר זמני הקרנה אינו שגיאה: צפו לסטטוס 200 ולמערך `results` ריק. גם `country` חסר או לא תקין אינו שגיאה. ראו [שגיאות](https://amodb.dev/he/errors/) ו[מגבלות קצב](https://amodb.dev/he/rate-limits/). ## הערות מעשיות - הכיסוי משתנה לפי מדינה וכותר. התייחסו למערך `results` ריק כאל לא ידוע, ולא כאל לא מוקרן. - הציגו את `start` בדיוק כפי שהוחזר. זו השעה המקומית של בית הקולנוע בלי הפרש UTC, והשעון של בית הקולנוע הוא מה שמבקרים מצפים לראות. - זמני הקרנה נשמרים בקצה במטמון 30 דקות. אל תבקשו אותם בכל צפייה בעמוד, והשאירו את המטמון שלכם קצר. - השתמשו שוב באותה רשימת סרטים שמוקרנים עכשיו לכל המבקרים באזור. גם היא נשמרת בקצה 30 דקות. - השתמשו ב-`booking_url` כדי לשלוח מבקר לעמוד ההזמנה של בית הקולנוע. הוא `null` כשבית הקולנוע לא נותן קישור. - לסקירת מקרי השימוש ראו [API זמני הקרנות בקולנוע](https://amodb.dev/he/cinema-showtimes-api/), ולנתונים האחרים של סרט ראו [סרטים](https://amodb.dev/he/movies/). ## שאלות ותשובות ### האם הפרמטר country חובה? לא, אבל צריך אותו כדי לקבל בתי קולנוע. שלחו קוד של שתי אותיות כמו RU או DE. בלי country, או עם קוד שאינו בן שתי אותיות, results ריק ורשימת countries מראה איפה יש זמני הקרנה. הפרמטר region עובד ככינוי. ### מה אומר מערך results ריק? זה אומר שלא ידועים זמני הקרנה לכותר הזה במדינה הזו מהיום והלאה. זה לא מוכיח שהסרט לא מוקרן. הרשימה countries עדיין מראה מדינות אחרות עם נתונים. הציגו במקום זה את תאריך היציאה מפרטי הסרט. ### איך מוצאים סרטים שמוקרנים עכשיו בקולנוע? קראו ל-GET /3/movie/now_playing עם הפרמטר region, ואז בקשו זמני הקרנה למזהים שמעניינים אתכם. הרשימה נשמרת במטמון 30 דקות, ולכן אפשר להשתמש בה שוב לכל מבקר. ### האם הזמנים באזור הזמן של המבקר? לא. הערך start הוא השעה המקומית בבית הקולנוע וללא הפרש UTC. לכל בית קולנוע יש גם timezone כמו Europe/Moscow. הציגו את start כפי שהוחזר ואל תמירו אותו לפי אזור הזמן של המבקר. ## עמודים קשורים - [API זמני הקרנה בקולנוע](https://amodb.dev/he/cinema-showtimes-api/): API זמני הקרנה בקולנוע: GET /3/movie/{movie_id}/showtimes עם קוד מדינה מחזיר בתי קולנוע, שעות התחלה ופורמטים כשהם ידועים. שלבו אותו עם 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/ratings/): API דירוגי סרטים וסדרות שמחזיר ציוני IMDb, Kinopoisk, Metacritic, Rotten Tomatoes ו-TMDB לכותר בקריאה אחת, עם value ו-votes ו-null לכל מקור שאינו ידוע. - [מגבלות קצב](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/showtimes/