# Turkey Cinema Search API

> Search live showtimes, movies, and theaters across Turkey. Built for AI agents:
> no auth, no SQL — one search endpoint with simple filters, JSON in/out.

Live data: 110 theaters, 80 movies, 13689 sessions (2026-08-01 to 2026-08-08)

## Current time (use this to resolve relative dates)

- Now: 2026-08-02T00:03 (Sunday, Europe/Istanbul (UTC+3))
- Today: 2026-08-02
- Tomorrow: 2026-08-03

Every API response includes the same `time` object — never guess the date.

## For AI assistants: how to call this API

If you can fetch or open web pages, you can use this API — **opening a GET URL
below with your browsing/fetch tool IS the API call**. The response is plain
JSON. No API key, no auth, no special headers, no POST required — every search
works as a plain GET link. Fetch it, parse the JSON, answer the user.

## Endpoints

1. `GET /` — Full API documentation + live meta (JSON)
2. `GET /openapi.json` — OpenAPI 3.1 spec (alias: /swagger)
3. `GET /api/meta` — Available filter values (cities, genres, age ratings, formats, languages, date range)
4. `GET /api/search?...` — Search via query string
5. `POST /api/search` — Search via JSON body

## Search — two ways

**GET** (query string — works in any browser, fetch tool, or agent):
```
https://cinema.siberofis.com/api/search?type=sessions&city=Istanbul&date=2026-08-02
```

**POST** (JSON body — for programmatic use):
```
POST /api/search
Content-Type: application/json

{
  "type": "sessions" | "movies" | "theaters",
  "filters": { ... }
}
```

## Available filters

| Filter | Description | Example |
|--------|-------------|---------|
| `city` | City name (see meta.cities) | "Istanbul", "Ankara" |
| `side` | Istanbul side — "anadolu" (Asian) or "avrupa" (European). Implies Istanbul; no city needed | "anadolu" |
| `genre` | One genre, partial match (see meta.genres). Query genres separately for OR logic | "Komedi", "Animasyon" |
| `movie` | Movie title, partial match (Turkish or original title) | "Minecraft" |
| `theater` | Theater name, partial match | "Cinemaximum" |
| `date` | Single date YYYY-MM-DD | "2026-08-03" |
| `date_from` | Start of date range | "2026-08-01" |
| `date_to` | End of date range | "2026-08-08" |
| `time_from` | Sessions at or after HH:MM | "14:00" |
| `time_to` | Sessions at or before HH:MM | "22:00" |
| `format` | "2D" or "3D" | "3D" |
| `language` | "Altyazili" (subtitled) or "Dublaj" (dubbed) | "Dublaj" |
| `age_rating` | Exact rating match (available: G, Genel İzleyici Kitlesi, 6+, 6A, 10+, 10A, PG, 13+, 13A, PG-13, 16+, R, 18+) | "13+" |
| `age_rating_max` | Numeric age limit — include films rated up to N (unrated films included). Prefer this for kids | 11 |
| `limit` | Max results, default 100, max 1000 | 50 |

## Worked example — natural language to API call

User asks: "Tomorrow I'm taking my 11-year-old son to a fun movie on the Asian side
of Istanbul, after 2 pm." Resolve it like this:

- tomorrow → `date=2026-08-03` (from the `time` object above)
- Asian side of Istanbul → `side=anadolu`
- after 2 pm → `time_from=14:00`
- 11-year-old → `age_rating_max=11`
- "fun" → pick kid-friendly genres: Animasyon, Aile, Komedi, Macera (one query per genre, or omit genre and filter by age only)

Fetch this URL (it returns JSON):
```
https://cinema.siberofis.com/api/search?type=sessions&side=anadolu&date=2026-08-03&time_from=14:00&age_rating_max=11&genre=Animasyon
```

Each result contains session (time, format, language, booking_url), movie
(title, genres, duration, age_rating, poster) and theater (name, city, side,
address, lat/lon). Give the user the `booking_url` to buy tickets.

## Other examples

Subtitled sessions tonight on Istanbul's European side:
```
https://cinema.siberofis.com/api/search?type=sessions&side=avrupa&date=2026-08-02&time_from=19:00&language=Altyazili
```

All comedy movies currently showing:
```
https://cinema.siberofis.com/api/search?type=movies&genre=Komedi
```

Theaters in Ankara:
```
https://cinema.siberofis.com/api/search?type=theaters&city=Ankara
```

## Available cities

Adana, Afyonkarahisar, Ankara, Antalya, Aydın, Bolu, Bursa, Denizli, Diyarbakır, Edirne, Erzurum, Eskişehir, Gaziantep, Hatay, Istanbul, Kahramanmaraş, Kayseri, Kocaeli, Konya, Kütahya, Kırklareli, Kırıkkale, Manisa, Mersin, Muğla, Osmaniye, Sakarya, Samsun, Tekirdağ, Trabzon, Van, Zonguldak, Çanakkale, Çorum, İzmir, Şanlıurfa

## Available genres

Aile, Aksiyon, Animasyon, Bilim Kurgu, Dram, Fantastik, Gerilim, Gizem, IMAX, Komedi, Korku, Macera, Romantik

## Notes

- All dates YYYY-MM-DD, all times HH:MM (24h), timezone Europe/Istanbul (UTC+3)
- `side` only applies to Istanbul (anadolu = Asian side, avrupa = European side)
- `type=movies` returns one entry per film — data is merged across cinema chains and sorted by session count (most shown first)
- `format`/`language` may be null in results — it means unknown, not a reason to exclude a session
- `filters_applied` in every response echoes what was understood — verify it matches your intent
- Data refreshes several times a day from the cinema chains' own sites