Venues & auditoriums

Physical cinemas, auditoriums and a cinema’s programme.

Production · organization access required

Requests require an active organization grant and an API key or Clerk session. Results respect your granted scopes and markets. Access details →

GET`/v1/venues`

Physical cinema venues.

Parameters

Name	Type	Details
`limit`query · optional	`integer`	Default: 50 · Minimum: 1 · Maximum: 100
`cursor`query · optional	`string`	Opaque cursor from the previous response. Preserve the same filters.
`countryCode`query · optional	`string`	Optional two-letter country filter. This narrows results; it does not grant access.Pattern: ^[A-Za-z]{2}$
`marketId`query · optional	`string`	Public market identifier (mkt_…).
`operatorId`query · optional	`string`	Public operator identifier (opr_…).

Shell · authenticated request

curl "https://api.boxobserver.com/v1/venues" \
  -H "Authorization: Bearer $BOX_OBSERVER_API_KEY"

Response

200 application/json · Success shape within your granted access.

Illustrative response shape · not live data

{
  "data": [],
  "page": {
    "nextCursor": null,
    "hasMore": false
  },
  "meta": {
    "requestId": "example-request-id",
    "generatedAt": "2026-09-04T12:00:00.000Z"
  }
}

Response fields

Field	Type and constraints
`data`Required	`array<object>`
`data[].id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].name`Required	`string`
`data[].programmingType`Required	`string`Values: mainstream, mixed, specialist
`data[].address`Required	`string \| null`
`data[].latitude`Required	`number \| null`Minimum: -90 · Maximum: 90
`data[].longitude`Required	`number \| null`Minimum: -180 · Maximum: 180
`data[].market`Required	`object`
`data[].market.id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].market.name`Required	`string`
`data[].market.countryCode`Required	`string`
`data[].market.timeZone`Required	`string`
`data[].operatorId`Required	`string \| null`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`page`Required	`object`
`page.nextCursor`Required	`string \| null`
`page.hasMore`Required	`boolean`
`meta`Required	`object`
`meta.requestId`Required	`string`
`meta.generatedAt`Required	`string`Format: date-time

Errors: 400, 401, 403, 429, 500, 503. Response format and retry guidance →

GET`/v1/venues/{id}`

Physical cinema venue.

Replace {id} with the appropriate public identifier returned by the API.

Parameters

Name	Type	Details
`id`path · required	`string`	Public resource identifier returned by the API.

Shell · authenticated request

curl "https://api.boxobserver.com/v1/venues/{id}" \
  -H "Authorization: Bearer $BOX_OBSERVER_API_KEY"

Response

200 application/json · Success shape within your granted access.

Illustrative response shape · not live data

{
  "data": {
    "id": "ven_ZXhhbXBsZQ",
    "name": "example",
    "programmingType": "mainstream",
    "address": null,
    "latitude": null,
    "longitude": null,
    "market": {
      "id": "mkt_ZXhhbXBsZQ",
      "name": "example",
      "countryCode": "RO",
      "timeZone": "Europe/Bucharest"
    },
    "operatorId": null
  },
  "meta": {
    "requestId": "example-request-id",
    "generatedAt": "2026-09-04T12:00:00.000Z"
  }
}

Response fields

Field	Type and constraints
`data`Required	`object`
`data.id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data.name`Required	`string`
`data.programmingType`Required	`string`Values: mainstream, mixed, specialist
`data.address`Required	`string \| null`
`data.latitude`Required	`number \| null`Minimum: -90 · Maximum: 90
`data.longitude`Required	`number \| null`Minimum: -180 · Maximum: 180
`data.market`Required	`object`
`data.market.id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data.market.name`Required	`string`
`data.market.countryCode`Required	`string`
`data.market.timeZone`Required	`string`
`data.operatorId`Required	`string \| null`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`meta`Required	`object`
`meta.requestId`Required	`string`
`meta.generatedAt`Required	`string`Format: date-time

Errors: 400, 401, 403, 404, 429, 500, 503. Response format and retry guidance →

GET`/v1/venues/{id}/auditoriums`

Venue auditoriums.

Replace {id} with the appropriate public identifier returned by the API.

Parameters

Name	Type	Details
`id`path · required	`string`	Public resource identifier returned by the API.
`limit`query · optional	`integer`	Default: 50 · Minimum: 1 · Maximum: 100
`cursor`query · optional	`string`	Opaque cursor from the previous response. Preserve the same filters.

Shell · authenticated request

curl "https://api.boxobserver.com/v1/venues/{id}/auditoriums" \
  -H "Authorization: Bearer $BOX_OBSERVER_API_KEY"

Response

200 application/json · Success shape within your granted access.

Illustrative response shape · not live data

{
  "data": [],
  "page": {
    "nextCursor": null,
    "hasMore": false
  },
  "meta": {
    "requestId": "example-request-id",
    "generatedAt": "2026-09-04T12:00:00.000Z"
  }
}

Response fields

Field	Type and constraints
`data`Required	`array<object>`
`data[].id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].venueId`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].name`Required	`string`
`data[].capacity`Required	`integer \| null`Minimum: 0
`data[].experiences`Required	`array<string> \| null`
`page`Required	`object`
`page.nextCursor`Required	`string \| null`
`page.hasMore`Required	`boolean`
`meta`Required	`object`
`meta.requestId`Required	`string`
`meta.generatedAt`Required	`string`Format: date-time

Errors: 400, 401, 403, 429, 500, 503. Response format and retry guidance →

GET`/v1/venues/{id}/showings`

Venue showings.

Replace {id} with the appropriate public identifier returned by the API.

Parameters

Name	Type	Details
`id`path · required	`string`	Public resource identifier returned by the API.
`limit`query · optional	`integer`	Default: 50 · Minimum: 1 · Maximum: 100
`cursor`query · optional	`string`	Opaque cursor from the previous response. Preserve the same filters.
`scope`query · optional	`string`	Defaults to current (D1-owned). Archived selects published history; all explicitly combines both. Ownership is independent of Showing or premiere dates. Archived/all requires history:read.Values: current, archived, all
`releaseId`query · optional	`string`	Public country Release identifier (crl_…).
`movieId`query · optional	`string`	Public canonical movie identifier (mov_…).
`operatorId`query · optional	`string`	Public operator identifier (opr_…).
`marketId`query · optional	`string`	Public market identifier (mkt_…).
`countryCode`query · optional	`string`	Optional two-letter country filter. This narrows results; it does not grant access.Pattern: ^[A-Za-z]{2}$
`localDate`query · optional	`string`	Cinema-local calendar date, YYYY-MM-DD. Cannot be combined with timestamp bounds.
`startsFrom`query · optional	`string`	Inclusive start timestamp. ISO 8601; offsets are normalized to UTC.
`startsBefore`query · optional	`string`	Exclusive end timestamp. The schedule window is limited to 31 days.

Shell · authenticated request

curl "https://api.boxobserver.com/v1/venues/{id}/showings" \
  -H "Authorization: Bearer $BOX_OBSERVER_API_KEY"

Response

200 application/json · Success shape within your granted access.

Illustrative response shape · not live data

{
  "data": [],
  "page": {
    "nextCursor": null,
    "hasMore": false
  },
  "meta": {
    "requestId": "example-request-id",
    "generatedAt": "2026-09-04T12:00:00.000Z"
  }
}

Response fields

Field	Type and constraints
`data`Required	`array<object>`
`data[].id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].releaseId`Required	`string \| null`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].status`Required	`string`Values: scheduled, unlisted, cancelled
`data[].startsAt`Required	`string`Format: date-time
`data[].localDate`Required	`string`Format: date
`data[].timeZone`Required	`string`
`data[].venue`Required	`object`
`data[].venue.id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].venue.name`Required	`string`
`data[].venue.programmingType`Required	`string`Values: mainstream, mixed, specialist
`data[].venue.market`Required	`object`
`data[].venue.market.id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].venue.market.name`Required	`string`
`data[].venue.market.countryCode`Required	`string`
`data[].venue.market.timeZone`Required	`string`
`data[].auditorium`Required	`object \| null`
`data[].auditorium.id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].auditorium.name`Required	`string`
`data[].auditorium.capacity`Required	`integer \| null`Minimum: 0
`data[].auditorium.experiences`Required	`array<string> \| null`
`data[].movie`Required	`object`
`data[].movie.canonicalMovie`Required	`object \| null`
`data[].movie.canonicalMovie.id`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].movie.canonicalMovie.title`Required	`string`
`data[].movie.canonicalMovie.originalTitle`Required	`string \| null`
`data[].movie.canonicalMovie.releaseYear`Required	`integer \| null`
`data[].movie.canonicalMovie.runtimeMinutes`Required	`integer \| null`Minimum: 0
`data[].movie.sourceTitle`Required	`string`
`data[].movie.sourceOriginalTitle`Required	`string \| null`
`data[].movie.identityStatus`Required	`string`Values: canonical, source
`data[].format`Required	`string`Values: 2d, 3d
`data[].experiences`Required	`array<string>`
`data[].experienceSource`Required	`string \| null`Values: showing, auditorium,
`data[].language`Required	`string \| null`
`data[].capacity`Required	`integer \| null`Minimum: 0
`data[].capacitySource`Required	`string \| null`Values: showing, observation, auditorium,
`data[].price`Required	`object`
`data[].price.status`Required	`string`Values: exact, derived, unavailable
`data[].price.amountMinor`Required	`integer \| null`Minimum: 0
`data[].price.currency`Required	`string \| null`
`data[].price.source`Required	`string \| null`Values: providerSchedule, providerBooking, officialTariff, legacyUnknown,
`data[].price.observedAt`Required	`string \| null`Format: date-time
`data[].price.lastConfirmedAt`Required	`string \| null`Format: date-time
`data[].price.options`Optional	`array<object>`Default: []
`data[].price.options[].offerKey`Required	`string`Pattern: ^(mkt\|opr\|ven\|aud\|mov\|shw\|dst\|rel\|crl\|pof)_[A-Za-z0-9_-]+$
`data[].price.options[].label`Required	`string`
`data[].price.options[].amountMinor`Required	`integer`Minimum: 0
`data[].price.options[].currency`Required	`string`
`data[].price.options[].admissionsIncluded`Required	`integer`Minimum: 0
`data[].seatAvailability`Required	`object \| null`
`data[].seatAvailability.status`Required	`string`Values: exact, derived, unavailable
`data[].seatAvailability.observedAt`Required	`string`Format: date-time
`data[].seatAvailability.checkpoint`Required	`string`
`data[].seatAvailability.capacity`Required	`integer \| null`Minimum: 0
`data[].seatAvailability.availableSeats`Required	`integer \| null`Minimum: 0
`data[].seatAvailability.occupiedEstimate`Required	`integer \| null`Minimum: 0
`data[].seatAvailability.occupancyRatio`Required	`number \| null`Minimum: 0 · Maximum: 1
`data[].updatedAt`Required	`string`Format: date-time
`page`Required	`object`
`page.nextCursor`Required	`string \| null`
`page.hasMore`Required	`boolean`
`meta`Required	`object`
`meta.requestId`Required	`string`
`meta.generatedAt`Required	`string`Format: date-time

Errors: 400, 401, 403, 429, 500, 503. Response format and retry guidance →

Venues & auditoriums

GET/v1/venues

Parameters

Response

GET/v1/venues/{id}

Parameters

Response

GET/v1/venues/{id}/auditoriums

Parameters

Response

GET/v1/venues/{id}/showings

Parameters

Response

GET`/v1/venues`

GET`/v1/venues/{id}`

GET`/v1/venues/{id}/auditoriums`

GET`/v1/venues/{id}/showings`