Datasets

What's published

Two datasets, both covering every venue Clusterflick lists. Both are free to use, including commercially, under CC BY 4.0 as long as you credit Clusterflick; the film metadata from The Movie Database inside them isn't ours to license. The data licence has the terms.

• A JSON file for each venue, listing its showings in a shared schema. The fullest form of the data, and the one to build on.

• An iCalendar file for each venue, to subscribe to or hand to anything that reads ICS.

Where to get it

Every file has a fixed address, so you can link to it, subscribe to it, or fetch it on a schedule.

Index

https://clusterflick.com/datasets/index.json

Latest releases

https://clusterflick.com/datasets/latest.json

Data file per venue

https://clusterflick.com/datasets/venues/<venue-id>.json

Calendar file per venue

https://clusterflick.com/datasets/calendars/<venue-id>.ics

JSON schema

https://clusterflick.com/datasets/schema.json

Start from the index. It lists every venue by id with its name, type, address, coordinates and page on Clusterflick, and the files published for it. All of these files can be read from a browser on any site.

Only the latest data is hosted here. Every earlier release is kept on GitHub, for the data files and the calendars, if you need to look back.

The schema

The per-venue JSON files follow a published JSON Schema.

The schema is the one the pipeline checks every venue's file against before it is released, so it describes the files as published. It is stable in practice but not frozen: it changes when the pipeline needs it to, with the aim of staying backwards compatible.

The calendar feeds are standard iCalendar. Each event links to the film's page here, and the feed's X-WR-CALDESC carries the credit the licence asks for.

How often it changes

New data is released several times a day, as the pipeline runs.

Each pipeline run releases both datasets, the calendar feeds a few minutes after the data files they are built from. The files here are replaced when the site next deploys after a release. The release history shows how often that has happened and at what time of day.

The files are cached for up to ten minutes, so there is nothing to gain from fetching them more than once an hour.

Checking for new data

Poll latest.json, and compare its release tags with the ones you saw last.

latest.json is a few hundred bytes: the release each dataset was built from, exactly as the index gives it, and nothing else. Fetch it as often as once an hour, and only fetch the rest when a tag has changed.

{
  "generatedAt": "2026-10-26T06:03:54.611Z",
  "releases": {
    "data": {
      "repository": "clusterflick/data-transformed",
      "tag": "20261026.050352",
      "publishedAt": "2026-10-26T05:07:56Z"
    },
    "calendar": {
      "repository": "clusterflick/data-calendar",
      "tag": "20261026.051820",
      "publishedAt": "2026-10-26T05:18:21Z"
    }
  }
}

Compare the tag of the dataset you use, not generatedAt. The site deploys more than once for each release, and generatedAt moves with every deploy whether the data changed or not.

const response = await fetch("https://clusterflick.com/datasets/latest.json");
const { releases } = await response.json();

if (releases.data.tag !== lastSeenTag) {
  // New data: fetch index.json and the venue files you need
  lastSeenTag = releases.data.tag;
}