קבלת מפתח API

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

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

עודכן צפייה כ-Markdown

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

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

הדוגמה מבקשת את Fight Club ברוסיה ומטפלת בתשובה ריקה.

bashjspyphpgo 
curl -sf "https://api.amodb.dev/3/movie/550/showtimes?country=RU" \
  -H "Authorization: Bearer $AMODB_KEY"
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);
  }
}
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
$url = 'https://api.amodb.dev/3/movie/550/showtimes?country=RU';
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => 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;
    }
}
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.

שדות התגובה

שדהסוגהערות
idintegerמזהה הסרט.
countrystring או nullהקוד באותיות גדולות שביקשתם, או null כש-country חסר או שאינו בן שתי אותיות.
resultsarrayאובייקט אחד לכל בית קולנוע, ממוין לפי בית הקולנוע. ריק כשלא ידוע דבר או שלא נשלחה מדינה. לכל היותר 1500 הקרנות בסך הכול.
results[].idintegerמזהה בית הקולנוע.
results[].namestringשם בית הקולנוע.
results[].chainobjectkey הוא מפתח הרשת, ו-name הוא שם הרשת או null.
results[].citystring או nullעיר.
results[].regionstring או nullאזור.
results[].addressstring או nullכתובת רחוב.
results[].postal_codestring או nullמיקוד.
results[].countrystringקוד המדינה של בית הקולנוע.
results[].timezonestring או nullאזור זמן של IANA כמו Europe/Moscow.
results[].latitude, results[].longitudenumber או nullמיקום בית הקולנוע.
results[].phonestring או nullמספר טלפון.
results[].urlstring או nullעמוד בית הקולנוע.
results[].showtimesarrayהקרנות באותו בית קולנוע, ממוינות לפי שעת התחלה.
results[].showtimes[].datestringהיום בצורה 2026-10-18.
results[].showtimes[].startstringהתחלה בשעה המקומית של בית הקולנוע, כמו 2026-10-18T21:40, בלי הפרש UTC.
results[].showtimes[].endstring או nullסיום בשעה המקומית של בית הקולנוע.
results[].showtimes[].auditoriumstring או nullשם האולם.
results[].showtimes[].formatsarray of stringsפורמטים כמו 2D.
results[].showtimes[].tagsarray of stringsתוויות נוספות. לרוב ריק.
results[].showtimes[].audio, subtitles, languagestring או nullפרטי שמע, כתוביות ושפה כשהם ידועים.
results[].showtimes[].pricenumber או nullמחיר כרטיס.
results[].showtimes[].currencystring או nullהמטבע של price.
results[].showtimes[].pricesany או nullפרטי מחיר כשלבית קולנוע יש כמה מחירים.
results[].showtimes[].booking_urlstring או nullקישור להזמנת מקום.
results[].showtimes[].sold_outbooleantrue כשההקרנה אזלה.
countriesarrayסיכום לפי מדינה, ראו בהמשך.

קראו את המפתחות שאתם משתמשים בהם לפי שם ודלגו על מפתחות נוספים בתוך אובייקט של בית קולנוע או הקרנה. הרבה שדות הם 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 מדינות שעדיין יש בהן הקרנה, ראשונה המדינה עם הכי הרבה הקרנות. השתמשו בו כדי לדעת איפה כותר מוקרן לפני שמבקשים בתי קולנוע.

curl 
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[].countrystringקוד של שתי אותיות, מוכן לשימוש כפרמטר country.
countries[].namestringשם המדינה באנגלית.
countries[].venuesintegerבתי קולנוע עם הקרנה.
countries[].citiesintegerערים עם הקרנה.
countries[].showtimesintegerהקרנות מהיום והלאה.
countries[].first_day, countries[].last_daystringהיום הראשון והאחרון עם הקרנה.

קוד מדינה בלי נתונים, כמו 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

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

שלבבקשהתוצאה
1GET /3/movie/now_playing?region=RU&page=1עד 20 סרטים בעמוד, נשמר במטמון 30 דקות
2GET /3/movie/{id}/showtimes?country=RU לכל מזההבתי קולנוע וזמנים, איפה שידוע

הלולאה שלמטה מנסה שוב פעם או פעמיים כשמגיעים לגבול המסלול, וממתינה את מספר השניות שב-Retry-After.

JavaScript 
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 בקשות לדקה זה ממצה את כל החלון, ולכן שמרו את התוצאה במטמון בצד שלכם. את פרמטרי הרשימות ראו בעמוד פופולריים ורשימות.

שגיאות

גוף השגיאה עוקב אחרי TMDB: success, status_code ו-status_message. מפתח שגוי נותן status_code 7.

HTTPstatus_codeמתי
4017המפתח חסר או שגוי.
40236תקופת המסלול הסתיימה.
40434אין סרט עם המזהה הזה.
42925מעל הבקשות שלכם לדקה. המתינו Retry-After שניות.

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

הערות מעשיות

  • הכיסוי משתנה לפי מדינה וכותר. התייחסו למערך results ריק כאל לא ידוע, ולא כאל לא מוקרן.
  • הציגו את start בדיוק כפי שהוחזר. זו השעה המקומית של בית הקולנוע בלי הפרש UTC, והשעון של בית הקולנוע הוא מה שמבקרים מצפים לראות.
  • זמני הקרנה נשמרים בקצה במטמון 30 דקות. אל תבקשו אותם בכל צפייה בעמוד, והשאירו את המטמון שלכם קצר.
  • השתמשו שוב באותה רשימת סרטים שמוקרנים עכשיו לכל המבקרים באזור. גם היא נשמרת בקצה 30 דקות.
  • השתמשו ב-booking_url כדי לשלוח מבקר לעמוד ההזמנה של בית הקולנוע. הוא null כשבית הקולנוע לא נותן קישור.
  • לסקירת מקרי השימוש ראו API זמני הקרנות בקולנוע, ולנתונים האחרים של סרט ראו סרטים.