Data conventions
Identifiers, dates, prices and seat observations.
Identifiers and relationships
Treat public IDs and cursors as opaque strings. Keep their prefixes, store them unchanged and use IDs returned by the API. They are identifiers, not secrets or authorization credentials.
| Prefix | Entity |
|---|---|
mkt_ | Market |
opr_ | Operator |
ven_ | Venue |
aud_ | Auditorium |
mov_ | Movie |
shw_ | Showing |
dst_ | Distributor |
rel_ | Calendar announcement |
crl_ | Country Release |
pof_ | Price offer |
A showing can retain a provider title before it is matched to a canonical movie. Check movie.identityStatus; canonicalMovie may be null. Movie IDs, country Release IDs and calendar announcement IDs identify different entities. A Showing has a nullable releaseId for its country run; unresolved Showings may not yet belong to a Release.
Dates and timestamps
startsAt is an absolute timestamp. localDate is the cinema’s calendar date in its stated timeZone, usually Europe/Bucharest for the current Romanian dataset. Do not derive a local date by slicing a UTC timestamp.
Timestamp filters accept ISO 8601 offsets and are normalized to UTC. Calendar dates must exist: 2026-02-30 is rejected. meta.generatedAt is response creation time, not when the provider data was observed.
Seat observations
Unavailable seats can include reservations and holds. A pre-show snapshot does not establish final attendance or revenue.
seatAvailability describes an observed snapshot with its own timestamp and checkpoint. occupancyRatio is a fraction between 0 and 1; multiply by 100 for a percentage.
The showing projection uses the latest confirmed availability record only when it matches the current scheduled start and auditorium. The history endpoint retains earlier observations, including observations for a previous start time. Inspect scheduledStartAt before comparing them.
Missing observations stay null. A measured zero remains zero. Never replace unknown capacity or availability with zero.
Published prices
amountMinor is an integer in minor currency units: 3500 with RON represents 35.00 lei. Keep the currency alongside the amount.
options may include bundles; check admissionsIncluded. observedAt records when the current price menu became effective; lastConfirmedAt records its latest confirmation. An unchanged menu need not create a new observation.
Coverage and freshness
Public schedules, release calendars, catalogue records and seat observations update independently. A release date does not confirm that a cinema has booked the film. Missing showings do not establish an empty auditorium or available screen time.