Box Observer Docs
Open app
API / Reference

Markets

Cinema markets, geographic context and available population profiles.

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/markets

Cinema markets.

Parameters

NameTypeDetails
limitquery · optionalintegerDefault: 50 · Minimum: 1 · Maximum: 100
cursorquery · optionalstringOpaque cursor from the previous response. Preserve the same filters.
countryCodequery · optionalstringOptional two-letter country filter. This narrows results; it does not grant access.Pattern: ^[A-Za-z]{2}$
Shell · authenticated request
curl "https://api.boxobserver.com/v1/markets" \
  -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
FieldType and constraints
dataRequiredarray<object>
data[].idRequiredstringPattern: ^(mkt|opr|ven|aud|mov|shw|dst|rel|crl|pof)_[A-Za-z0-9_-]+$
data[].nameRequiredstring
data[].countryCodeRequiredstring
data[].timeZoneRequiredstring
data[].latitudeRequirednumber | nullMinimum: -90 · Maximum: 90
data[].longitudeRequirednumber | nullMinimum: -180 · Maximum: 180
data[].profileRequiredobject | null
data[].profile.effectiveDateRequiredstringFormat: date
data[].profile.populationRequiredintegerMinimum: 0
data[].profile.age0To14RequiredintegerMinimum: 0
data[].profile.age15To24RequiredintegerMinimum: 0
data[].profile.age25To44RequiredintegerMinimum: 0
data[].profile.age45To64RequiredintegerMinimum: 0
data[].profile.age65PlusRequiredintegerMinimum: 0
pageRequiredobject
page.nextCursorRequiredstring | null
page.hasMoreRequiredboolean
metaRequiredobject
meta.requestIdRequiredstring
meta.generatedAtRequiredstringFormat: date-time

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

GET/v1/markets/{id}

Cinema market.

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

Parameters

NameTypeDetails
idpath · requiredstringPublic resource identifier returned by the API.
Shell · authenticated request
curl "https://api.boxobserver.com/v1/markets/{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": "mkt_ZXhhbXBsZQ",
    "name": "example",
    "countryCode": "RO",
    "timeZone": "Europe/Bucharest",
    "latitude": null,
    "longitude": null,
    "profile": null
  },
  "meta": {
    "requestId": "example-request-id",
    "generatedAt": "2026-09-04T12:00:00.000Z"
  }
}
Response fields
FieldType and constraints
dataRequiredobject
data.idRequiredstringPattern: ^(mkt|opr|ven|aud|mov|shw|dst|rel|crl|pof)_[A-Za-z0-9_-]+$
data.nameRequiredstring
data.countryCodeRequiredstring
data.timeZoneRequiredstring
data.latitudeRequirednumber | nullMinimum: -90 · Maximum: 90
data.longitudeRequirednumber | nullMinimum: -180 · Maximum: 180
data.profileRequiredobject | null
data.profile.effectiveDateRequiredstringFormat: date
data.profile.populationRequiredintegerMinimum: 0
data.profile.age0To14RequiredintegerMinimum: 0
data.profile.age15To24RequiredintegerMinimum: 0
data.profile.age25To44RequiredintegerMinimum: 0
data.profile.age45To64RequiredintegerMinimum: 0
data.profile.age65PlusRequiredintegerMinimum: 0
metaRequiredobject
meta.requestIdRequiredstring
meta.generatedAtRequiredstringFormat: date-time

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