# 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, 99 movies, 10846 sessions (2026-09-12 to 2026-09-19)

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

- Now: 2026-09-12T09:56 (Saturday, Europe/Istanbul (UTC+3))
- Today: 2026-09-12
- Tomorrow: 2026-09-13

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
6. `POST /mcp` — Model Context Protocol endpoint (see below)

## MCP connector

If your client speaks the Model Context Protocol, add `https://sinema.siberofis.com/mcp` as a
remote MCP server instead of calling the REST endpoints by hand. No auth, no
API key. Protocol `2026-07-28` (stateless) and the 2025-era
`initialize` handshake are both served on that one endpoint, so old and new
clients both work.

Tools: `find_showtimes` (the main one — what is on, where, when, with a booking
link), `whats_playing` (one merged entry per film), `find_theaters` (cinemas by
city, with coordinates), `get_filter_values` (the real filter values — call this
before guessing one).

Every tool result carries `total_count` and `truncated`. **`truncated: true`
means the list was cut, not that nothing else exists.** Showtimes are ordered by
time, so a truncated query loses the END of the day — narrowing with `time_from`
usually beats paging with `offset`.

## Search — two ways

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

**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-09-13" |
| `date_from` | Start of date range | "2026-09-12" |
| `date_to` | End of date range | "2026-09-19" |
| `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 |
| `district` | District/neighbourhood, resolved from the theater address | "Kadıköy" |
| `format` | Screen format; matches per token, so `IMAX` also finds `IMAX 3D` | "IMAX" |
| `limit` | Max results, default 100, max 1000 | 50 |
| `offset` | Skip N rows — page through a truncated result set | 100 |

Every search response carries `count` (rows in THIS response), `total_count`
(rows matching the filter), `truncated`, `limit` and `offset`. **If `truncated`
is `true` the list is cut — do not conclude "no such sessions" from it.** Raise
`limit` or page with `offset`. Sessions are ordered by time, so a truncated
session query drops the END of the day; narrowing with `time_from` is usually
better than paging.

Each movie block also carries `age_min` — the numeric form of `age_rating`
("6+", "6A", "PG" all resolve to a number). `age_rating_max` compares against
it. The label-to-number mapping is published in `meta.age_rating_map`.

## 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-09-13` (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://sinema.siberofis.com/api/search?type=sessions&side=anadolu&date=2026-09-13&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, chain, 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://sinema.siberofis.com/api/search?type=sessions&side=avrupa&date=2026-09-12&time_from=19:00&language=Altyazili
```

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

Theaters in Ankara:
```
https://sinema.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, Komedi, Korku, Macera, Müzikal, 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