# District Showtimes Scraper (`monknwarriors/district-showtimes-scraper`) Actor

Finds every showtime for a movie across the cinemas in a city on District (district.in) — dates, times, theatres, screen formats, ticket prices and live seats-available counts.

- **URL**: https://apify.com/monknwarriors/district-showtimes-scraper.md
- **Developed by:** [Monk N Warriors](https://apify.com/monknwarriors) (community)
- **Stats:** 2 total users, 1 monthly users, 80.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 showtime founds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## District Movie Showtimes & Cinema Schedule Scraper

Get every movie showtime across the cinemas in a city on **District**
(district.in) — dates, times, theatres, screen formats, ticket prices, and
how many seats are still free — in one structured dataset, without checking
cinema by cinema.

Built for cinema analysts, distributors tracking a release's rollout, price
and occupancy monitoring, and anyone who needs a city-wide view of what's
playing and how full it is.

***

### What you can do with it

- Track a movie's **rollout** across every cinema in a city, day by day.
- Monitor **ticket prices** per cinema and per seating class over time.
- Watch **seat availability / occupancy** fill up ahead of a release or across a weekend.
- Compare **formats** (2D / 3D / IMAX / 4DX) and premium screens across a city.
- Build a **cinema directory** for a city — names, addresses, chains, coordinates.

***

### Input

| Field | Description |
|---|---|
| **Cities** | One or more city names, e.g. `Mumbai`, `Bengaluru`, `Ahmedabad`. District covers 1,300+ Indian cities and towns, not just the metros. Matching is case-insensitive. |
| **Movies** | Optional. A District movie link (`https://www.district.in/movies/...-MV181196`), a `MV181196` code, or just a movie name. **Leave empty to capture every movie currently showing** in each city. |
| **Movies per city** | Used only when *Movies* is empty — caps how many now-showing movies are pulled per city (default 10). |
| **Which dates to check** | `Automatic` (recommended) checks exactly the dates District has released for the movie. Or pick specific dates / a date range. |
| **Stop looking after N days ahead** | Safety cap for Automatic mode (default 14). |
| **Include far-away cinemas** | District returns a secondary "also showing nearby" group (often a neighbouring town). Keep on to capture it (default on). |
| **Proxy** | Residential, India by default — District only serves Indian IPs. |

Minimal input — every movie showing in Mumbai, all released dates:

```json
{ "cities": ["Mumbai"] }
```

***

### Output

The dataset is **flat** — no nested columns — so it opens cleanly in Excel /
Google Sheets. **Pick one grain with the *Output mode* input; the whole
dataset is that grain, so every column has data** (no empty columns to
scroll past):

- **`SHOWTIMES`** (default) — one row per showtime: movie, cinema, time,
  price range, total seat counts, occupancy, and a `price_classes` text
  summary of every seating class.
- **`PRICE_CLASSES`** — one row per seating class per showtime: that class's
  price and live seat counts, structured for per-class analysis.

Both carry the same movie / cinema / showtime columns and the
`seat_layout_ref`.

#### `SHOWTIMES` grain — one row per showtime

(Illustrative — codes and numbers change constantly.)

```json
{
  "row_type": "SHOWTIME",
  "session_key": "district|mumbai|181196|1023314|20668|2026-09-08",
  "scraped_at": "2026-09-07T18:22:46+00:00",

  "city_key": "mumbai", "city_name": "Mumbai", "state_key": "maharashtra",

  "movie_id": "181196",
  "movie_code": "n5N_fTqZr8",
  "movie_title": "Mirzapur: The Movie",
  "movie_languages": "Hindi",
  "movie_genres": "Action, Crime, Thriller",
  "censor_rating": "A",
  "duration_min": 197,

  "cinema_id": "1023314",
  "cinema_name": "PVR C&B Square Chakala, Andheri East, Mumbai",
  "cinema_chain": "PVR",
  "cinema_address": "Andheri - Kurla Rd, Opp Acme Plaza, Chakala, Andheri East, Mumbai 400059",
  "cinema_pincode": "400059",
  "latitude": 19.112491, "longitude": 72.864875,
  "provider_id": "1707",
  "is_far_cinema": false,
  "distance_km": 2.29,

  "session_id": "20668",
  "provider_movie_code": "OB7YWB",
  "date": "2026-09-08",
  "show_datetime_ist": "2026-09-08T04:45:00+05:30",
  "close_datetime_ist": "2026-09-08T05:30:00+05:30",
  "screen_name": "SCREEN 3",
  "screen_format": "2D",
  "premium_label": "",
  "is_premium": false,
  "max_tickets": 10,
  "status_color": "G",
  "session_tags": "price_100_200, 2d, 8_am_to_12_pm, wheelchair_friendly",

  "min_price": 149.0,
  "max_price": 299.0,
  "seats_available_total": 277,
  "seats_total": 304,
  "occupancy_pct": 8.9,
  "price_class_count": 5,
  "price_classes": "CLASSIC ROWS 149: 39/39 | PRIME ROWS 149: 174/178 | RECLIINER ROWS 299: 13/15",

  "seat_layout_ref": "1023314|20668|1707|OB7YWB|n5N_fTqZr8|181196|mumbai|2026-09-08|2D"
}
```

#### `PRICE_CLASSES` grain — one row per seating class per showtime

```json
{
  "row_type": "PRICE_CLASS",
  "session_key": "district|mumbai|181196|1023314|20668|2026-09-08",
  "movie_title": "Mirzapur: The Movie",
  "cinema_name": "PVR C&B Square Chakala, Andheri East, Mumbai",
  "show_datetime_ist": "2026-09-08T04:45:00+05:30",

  "area_code": "QR",
  "area_label": "PRIME ROWS",
  "area_price": 149.0,
  "area_currency": "INR",
  "area_seats_available": 174,
  "area_seats_total": 178,
  "area_status_color": "G"
}
```

*(all the shared movie / cinema / showtime columns are on this row too — trimmed here for brevity)*

#### Field reference

| Field | Grain | Meaning |
|---|---|---|
| `row_type` | both | `SHOWTIME` or `PRICE_CLASS`. |
| `session_key` | both | Stable ID for the showtime — same value on every re-run, and the join key to the **Seat Availability Scraper**. |
| `scraped_at` | both | UTC timestamp of capture. |
| `city_key` / `city_name` / `state_key` | both | The resolved city. |
| `movie_id` / `movie_code` | both | District's IDs for the movie (and its language/format variant). |
| `movie_title`, `movie_languages`, `movie_genres`, `censor_rating`, `duration_min` | both | Movie metadata. Languages/genres are comma-separated strings. |
| `cinema_id`, `cinema_name`, `cinema_chain` | both | The theatre. `cinema_chain` e.g. `PVR`, `INOX`, `Cinepolis`, `City Gold`. |
| `cinema_address`, `cinema_pincode`, `latitude`, `longitude` | both | Location. |
| `is_far_cinema` | both | `true` if from District's secondary "also showing nearby" group. |
| `distance_km` | both | Distance from the city centre. |
| `session_id`, `provider_movie_code` | both | District's IDs for the showtime. |
| `date` | both | Show date (`YYYY-MM-DD`). |
| `show_datetime_ist` / `close_datetime_ist` | both | Start time and booking-close time, ISO-8601 with `+05:30`. |
| `screen_name`, `screen_format` | both | Auditorium label; `2D` / `3D` / `IMAX 2D` / `4DX` / … |
| `premium_label` / `is_premium` | both | Sound / premium-screen tag (e.g. `DOLBY 7.1`) and a flag. |
| `max_tickets` | both | Max tickets sellable in one booking. |
| `status_color` | both | District's fill indicator: `G` plenty, `Y` filling, `R` almost full, `D` sold out. |
| `session_tags` | both | Comma-separated filter tags (price band, format, time-of-day, amenities). |
| `seat_layout_ref` | both | Pipe-delimited reference — paste this column straight into the **Seat Availability Scraper**. |
| `min_price` / `max_price` | SHOWTIMES | Cheapest / dearest ticket for the showtime. |
| `seats_available_total` / `seats_total` | SHOWTIMES | Live free seats and screen capacity, summed across classes. |
| `occupancy_pct` | SHOWTIMES | `(seats_total − seats_available_total) / seats_total`, as a percentage. |
| `price_class_count` | SHOWTIMES | How many seating classes this showtime has. |
| `price_classes` | SHOWTIMES | One-line readable summary of every class: `<class> <price>: <available>/<total>`, pipe-separated. |
| `area_code` / `area_label` | PRICE\_CLASSES | The seating class. |
| `area_price` / `area_currency` | PRICE\_CLASSES | Its ticket price. |
| `area_seats_available` / `area_seats_total` | PRICE\_CLASSES | Live free / total seats in that class. |
| `area_status_color` | PRICE\_CLASSES | That class's own fill indicator. |

Also written to the run's key-value store: **`RUN_REPORT`** — which cities,
movies and dates were checked, counts found for each, and any errors.

#### Views

- **Overview** — the run's grain, key columns only (the Console hides the columns that don't apply).

***

### Notes

- **Dates:** District releases each movie's booking window on its own
  schedule. *Automatic* mode uses exactly the dates District lists for the
  movie — no guessing a number of days.
- **Seat counts are live** at the moment of capture — re-run to track how a
  showtime fills up.
- **India only.** Keep the proxy on Residential / India; other IPs are blocked.

***

### Pairs with

**District Cinema Seat Availability & Occupancy Scraper** — every row here
carries a `seat_layout_ref` ready to drop into it for a seat-by-seat
occupancy map.

# Actor input Schema

## `cities` (type: `array`):

Which cities to check, by name — e.g. "Mumbai", "Bengaluru", "Ahmedabad". District covers well over a thousand Indian cities and towns, not just the metros, so any city name works. Matching is case-insensitive; if a short name is ambiguous the run log will list the candidates so you can be more specific.

## `movies` (type: `array`):

Which movies to track. Accepts a District movie link (https://www.district.in/movies/...-MV181196), a bare code like MV181196, or just a movie name to search for. Leave this empty to automatically track everything currently showing in each city instead — see "Movies per city" below to cap how many.

## `maxMoviesPerCity` (type: `integer`):

Only used when Movies is left empty. Caps how many of the city's now-showing movies are checked, so a run doesn't grow unbounded.

## `dateMode` (type: `string`):

District publishes each movie's own booking window. "Automatic" reads that window straight from District (no guessing, no day-by-day probing) and checks exactly the dates it lists. Use the other modes to pin specific dates or a range.

## `maxDaysAhead` (type: `integer`):

A safety cap for "Automatic" — dates further out than this are ignored even if District lists them.

## `dates` (type: `array`):

Used only with "Only these exact dates". Each date as YYYY-MM-DD, e.g. 2026-09-08.

## `fromDate` (type: `string`):

Used only with "Every date in a range". YYYY-MM-DD, e.g. 2026-09-08.

## `toDate` (type: `string`):

Used only with "Every date in a range". YYYY-MM-DD, e.g. 2026-09-20.

## `includeFarCinemas` (type: `boolean`):

District splits results into nearby cinemas and a smaller "also showing, further away" group (often in a neighbouring town). Keep this on to capture both.

## `outputMode` (type: `string`):

"Showtimes": one row per showtime, with the price range, total seats, occupancy and a one-line price\_classes summary of every seating class. "Price classes": one row per seating class per showtime, structured (for per-class price / occupancy analysis). The dataset is one grain either way, so every column has data.

## `proxyConfiguration` (type: `object`):

Leave this on the default (Residential, India) — District expects requests from an Indian IP address and blocks ones that don't. This actor only fetches small JSON responses, so proxy usage stays low even on Residential.

## Actor input object example

```json
{
  "cities": [
    "Mumbai"
  ],
  "maxMoviesPerCity": 10,
  "dateMode": "AUTO",
  "maxDaysAhead": 14,
  "includeFarCinemas": true,
  "outputMode": "SHOWTIMES",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "IN"
  }
}
```

# Actor output Schema

## `showtimes` (type: `string`):

The default dataset — one row per showtime: movie, cinema, date, time, screen format, ticket price range, seats-available count, and a ready-to-use seat-layout reference for the District Cinema Seat Availability Scraper.

## `showtimesCsv` (type: `string`):

The same data as a spreadsheet-friendly CSV file.

## `runReport` (type: `string`):

Which cities, movies and dates were checked, how many showtimes were found for each, and any errors encountered.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "cities": [
        "Mumbai"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("monknwarriors/district-showtimes-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "cities": ["Mumbai"] }

# Run the Actor and wait for it to finish
run = client.actor("monknwarriors/district-showtimes-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "cities": [
    "Mumbai"
  ]
}' |
apify call monknwarriors/district-showtimes-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,monknwarriors/district-showtimes-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/F7lHm7jUYIIV8Uvya/builds/ELMxs9qMDKESX7Irh/openapi.json