Films and screenings in Madrid

Quick start

Download the current snapshot

1. Register or sign in, create a machine credential, and store it in a secret manager.
2. Send it as Authorization: Bearer $MFC_PARTNER_API_KEY when fetching /v1/current.json and the manifest.
3. Fetch its manifest_url and locate upcoming-films.ndjson.gz.
4. Request the payload with the same header, follow its one-minute signed R2 redirect without forwarding the API key, verify the SHA-256 checksum, and parse one JSON object per line.

export MFC_PARTNER_API_KEY='store-this-outside-your-code'
curl --fail \
  -H "Authorization: Bearer $MFC_PARTNER_API_KEY" \
  https://data.madridfilmcalendar.com/v1/current.json
# Use the same header for the manifest and payload gateway URL.
# Standard clients strip Authorization when redirected to the R2 host.

Coding agents

Using the API with a coding agent

If an agent is writing the integration, give it the contract and the task together. The prompt below contains the minimum context it needs to start without guessing the dataset shape.

Use the Madrid Film Calendar Bulk API v1.

Read the natural-language field guide before writing code:
https://data.madridfilmcalendar.com/docs#fields

Then use this public contract for structure and validation:
https://data.madridfilmcalendar.com/v1/openapi.json
https://data.madridfilmcalendar.com/v1/schemas/upcoming-film.schema.json

Start at https://data.madridfilmcalendar.com/v1/current.json, follow
manifest_url, and download upcoming-films.ndjson.gz.

Authenticate every data.madridfilmcalendar.com snapshot request with
Authorization: Bearer $MFC_PARTNER_API_KEY. Never put the key in a URL, log,
browser bundle, repository, prompt, or analytics event. The payload endpoint
redirects to R2; do not forward Authorization to the signed R2 URL.

There is one dataset; do not look for separate film or screening downloads.
Each NDJSON line is one upcoming-film record containing:
- film: the film and its Madrid Film Calendar research
- screenings: a non-empty array of current or future Madrid sessions

Verify the manifest and file SHA-256 checksums. Interpret showtime_local in
Europe/Madrid. Treat missing or nullable values as unknown, not false. Use
film_url and screening_url as the public links; do not invent direct cinema
ticket URLs.

My task is: [describe what you want to build]

The field guide explains what fields mean. OpenAPI and JSON Schema define their structure and validation rules. An integration should use both.

• Natural-language field guide
• OpenAPI 3.1
• Upcoming-film record schema

Feedback

What are you building?

The Partner API is new, and real integrations will shape what we document and improve next. If you are building an app, research project, visualization, or cultural tool, tell us what you are making, which fields you use, and where the contract gets in your way.

Tell us about your project

Dataset

Upcoming films

Field reference

Data dictionary

Each NDJSON line is an upcoming-film record. Arrays are written as []. Nullable fields may be null when the value is unknown.

Examples

Code examples

import gzip, hashlib, json, os, requests

base = "https://data.madridfilmcalendar.com"
auth = {"Authorization": f"Bearer {os.environ['MFC_PARTNER_API_KEY']}"}
current = requests.get(
    f"{base}/v1/current.json", headers=auth
).json()
manifest = requests.get(
    current["manifest_url"], headers=auth
).json()
file = next(
    x for x in manifest["files"]
    if x["path"] == "upcoming-films.ndjson.gz"
)
url = current["manifest_url"].replace(
    "manifest.json", file["path"]
)
redirect = requests.get(
    url, headers=auth, allow_redirects=False
)
redirect.raise_for_status()
# Deliberately omit Authorization on the cross-host signed request.
payload = requests.get(redirect.headers["Location"]).content
assert hashlib.sha256(payload).hexdigest() == file["sha256"]

for line in gzip.decompress(payload).decode("utf-8").splitlines():
    record = json.loads(line)
    film = record["film"]
    print(
        film["id"],
        film["title"]["original"],
        len(record["screenings"]),
    )

import { gunzipSync } from "node:zlib";

const base =
  "https://data.madridfilmcalendar.com";
const auth = {
  Authorization:
    `Bearer ${process.env.MFC_PARTNER_API_KEY}`
};
const current = await fetch(
  `${base}/v1/current.json`, { headers: auth }
).then(r => r.json());
const manifest = await fetch(
  current.manifest_url, { headers: auth }
).then(r => r.json());
const file = manifest.files.find(
  x => x.path === "upcoming-films.ndjson.gz"
);
const url = current.manifest_url.replace(
  "manifest.json", file.path
);
const redirect = await fetch(url, {
  headers: auth, redirect: "manual"
});
// Deliberately omit Authorization on the R2 request.
const compressed = Buffer.from(await fetch(
  redirect.headers.get("location")
).then(r => r.arrayBuffer()));
const upcomingFilms = gunzipSync(compressed)
  .toString("utf8")
  .trim()
  .split("\n")
  .map(JSON.parse);

API contract

Contract rules

Canonical IDs

Film and screening IDs belong to FDB and remain numeric in v1.

Madrid time

showtime_local is paired with timezone: Europe/Madrid.

First-party links

film_url opens the film page. screening_url opens that page with the exact session modal, where the genuine cinema ticket/info action is shown. Static UTM parameters identify partner API referrals.

Immutable versions

Published snapshot files never change. Corrections create a new version.

Breaking changes

Fields may be added compatibly within v1. Removing or changing meaning requires v2.

Snapshots

Versioning and updates

Store the last snapshot_version you processed. If it has not changed, there is nothing to download. When a film or screening is corrected, a new immutable version is published and current.json moves to it.

Compare the dataset's SHA-256 value in the manifest with the previous version to avoid processing unchanged content.

Terms

License and corrections

The snapshot dataset is licensed under Creative Commons Attribution 4.0. You may copy, modify, redistribute and use it commercially. When sharing the data or a substantial part of it, include the attribution from the active manifest and indicate your changes.

Attribution: Madrid Film Calendar FDB — https://data.madridfilmcalendar.com — licensed under CC BY 4.0. Snapshot: {snapshot_version}.

The license applies to Madrid Film Calendar's rights in the exported snapshot compilation, original research summaries and records. Citation links identify third-party evidence; they do not license those pages or their content. Madrid Film Calendar names, logos and trademarks are not licensed. Posters, licensed synopsis text, third-party ratings and other separately licensed material are excluded from this API. The manifest repeats this scope in machine-readable form.

The data is provided as-is, without warranty or endorsement by listed cinemas. To report an error, rights concern or removal request, email madridfilmcalendar@gmail.com; accepted corrections are published as a new immutable snapshot.

For machine-readable details, use the OpenAPI document and the published upcoming-film record schema.