Reference

API documentation

All API calls go to this origin. Every route requires a valid API key. Create keys from your account after you register (7-day trial after you verify your email). Commercial access is arranged offline. The playground is unauthenticated preview data only—it is not a substitute for the customer API.

Base URL

https://broadcast-calendar.cloud

Authentication

Send the key on every request using one of these headers:

Authorization: Bearer <your_api_key>
or X-API-Key: <your_api_key>

Create and revoke keys from the account page. The full key is shown only once.

Access and trial

The account email must be verified. You can call the v1 API while you have an active trial or while your account has a future access_until set by the operator (paid access granted offline). If both trial and access_until apply, the longer effective access wins for eligibility.

Rate limiting

By default, trial API keys (and all customer v1 API traffic) are limited to 3 requests per second per account, using a 1-second fixed window. If you exceed the limit, the API responds with 429 and a Retry-After header (seconds). Contact support if you need a higher sustained throughput for production.

Endpoints

All methods are GET and return JSON.

Channel IDs are UUIDs (e.g. aff8c27a-0765-4acc-8e41-58f8f75a49d7). Use the id returned from country channel lists or channel search in programme URLs.

Country codes must match ^[A-Za-z0-9-]+$ and be at most 16 characters. The catalog is mostly ISO 3166-1 alpha-2 codes (e.g. US, GB). On search, omit or leave country blank to match all countries.

List countries

GET /api/v1/countries

Returns every country that has at least one channel in the catalog, along with its channel count.

curl -s "https://broadcast-calendar.cloud/api/v1/countries" \
  -H "Authorization: Bearer YOUR_KEY"

Sample response

{
  "countries": [
    { "country": "AU", "channelCount": 605 },
    { "country": "CA", "channelCount": 1679 },
    { "country": "GB", "channelCount": 1368 },
    { "country": "IN", "channelCount": 2145 },
    { "country": "US", "channelCount": 11163 }
  ]
}

List channels in a country

GET /api/v1/countries/{country}/channels

Returns all channels for the given country code. Returns an empty channels array if the country has no channels.

Parameter	In	Type	Required	Description
country	path	string	yes	Country code: alphanumeric and hyphen, max 16 characters (e.g. US, GB, NO).

curl -s "https://broadcast-calendar.cloud/api/v1/countries/NO/channels" \
  -H "Authorization: Bearer YOUR_KEY"

Sample response

{
  "country": "NO",
  "channels": [
    {
      "id": "9ec49cca-5be4-4c77-9113-6716f73aa96e",
      "name": "NRK1",
      "icon": "https://example.com/nrk1.png",
      "needsReview": false,
      "country": "NO"
    },
    {
      "id": "3ad25d07-ea5d-4abe-a097-496e851143dd",
      "name": "TV 2",
      "icon": "",
      "needsReview": false,
      "country": "NO"
    }
  ]
}

Search channels

GET /api/v1/channels/search

Case-insensitive substring search on channel name. Empty or whitespace-only q returns an empty results array (HTTP 200).

Parameter	In	Type	Required	Description
q	query	string	yes	Search string; minimum 1 character after trim to return matches. Longer than 200 characters is truncated (not rejected). Up to 200 results, ordered by channel name (case-insensitive).
country	query	string	no	Optional country code (alphanumeric and hyphen, max 16 characters) to restrict results to one country.

curl -s "https://broadcast-calendar.cloud/api/v1/channels/search?q=news&country=US" \
  -H "Authorization: Bearer YOUR_KEY"

Sample response

{
  "results": [
    {
      "channelId": "bc452526-4c57-4120-be74-5ef0ab134ddb",
      "name": "7 NEWS MIAMI WSVN",
      "icon": "https://images.open-epg.com/x257.png",
      "country": "US",
      "needsReview": false
    },
    {
      "channelId": "e785c4a3-65b9-4c77-860e-5a5b233f044a",
      "name": "ABC News Live",
      "icon": "",
      "country": "US",
      "needsReview": false
    }
  ]
}

Channel programmes (schedule)

GET /api/v1/channels/{channelId}/programmes

Returns the broadcast schedule for a single channel, ordered by start ascending. start and stop are XMLTV datetime strings as stored upstream (e.g. 20260530180000 +0000, always UTC). No startISO or stopISO fields are returned.

Filter semantics:

Rolling window (omit days or days=N): programmes with parsed start ≥ now − N days (UTC). Default N is 7. There is no upper bound—all future programmes in the database are included if their start is on or after the cutoff.
Named days (days=today, tomorrow, yesterday): filter by start on that UTC calendar day only (half-open interval). Keywords are case-insensitive.
Full list (days=all, all=1, or all=true): all programmes for the channel.

Filtered responses exclude rows whose start does not parse as an XMLTV timestamp (included when days=all or all=1).

Parameter	In	Type	Required	Description
channelId	path	string (UUID)	yes	Channel UUID from the countries or search endpoints.
days	query	integer or keyword	no	Rolling lookback: integer 1–365 (default 7 when omitted). Calendar day (UTC): today, tomorrow, or yesterday (case-insensitive). Full list: all. Cannot be combined with all.
all	query	flag	no	Pass all=1 or all=true to return all programmes for this channel (same as days=all). Cannot be combined with days.

# Default — 7-day rolling lookback (UTC)
curl -s "https://broadcast-calendar.cloud/api/v1/channels/aff8c27a-0765-4acc-8e41-58f8f75a49d7/programmes" \
  -H "Authorization: Bearer YOUR_KEY"

# 14-day rolling lookback
curl -s "https://broadcast-calendar.cloud/api/v1/channels/aff8c27a-0765-4acc-8e41-58f8f75a49d7/programmes?days=14" \
  -H "Authorization: Bearer YOUR_KEY"

# Today (UTC calendar day)
curl -s "https://broadcast-calendar.cloud/api/v1/channels/aff8c27a-0765-4acc-8e41-58f8f75a49d7/programmes?days=today" \
  -H "Authorization: Bearer YOUR_KEY"

# Yesterday / tomorrow (UTC)
curl -s "https://broadcast-calendar.cloud/api/v1/channels/aff8c27a-0765-4acc-8e41-58f8f75a49d7/programmes?days=yesterday" \
  -H "Authorization: Bearer YOUR_KEY"
curl -s "https://broadcast-calendar.cloud/api/v1/channels/aff8c27a-0765-4acc-8e41-58f8f75a49d7/programmes?days=tomorrow" \
  -H "Authorization: Bearer YOUR_KEY"

# All available programmes
curl -s "https://broadcast-calendar.cloud/api/v1/channels/aff8c27a-0765-4acc-8e41-58f8f75a49d7/programmes?all=1" \
  -H "Authorization: Bearer YOUR_KEY"

Sample response

{
  "channelId": "aff8c27a-0765-4acc-8e41-58f8f75a49d7",
  "programmes": [
    {
      "id": "492193557",
      "start": "20260510050000 +0000",
      "stop": "20260510070000 +0000",
      "title": "20/20",
      "desc": "When a 16-year-old girl vanishes, her family investigates her disappearance.",
      "category": "Series, Newsmagazine",
      "sourceFileId": "740a0b92-b9ab-4040-a26d-fbc07fdcdb76",
      "needsReview": false,
      "updatedAt": "1778549841457"
    },
    {
      "id": "492193561",
      "start": "20260510070000 +0000",
      "stop": "20260510080000 +0000",
      "title": "What Would You Do?",
      "desc": "Using hidden cameras, host John Quiñones observes ordinary people confronted with dilemmas.",
      "category": "Newsmagazine",
      "sourceFileId": "740a0b92-b9ab-4040-a26d-fbc07fdcdb76",
      "needsReview": false,
      "updatedAt": "1778549841457"
    }
  ]
}

Errors

Error bodies are JSON with an error field (human-readable message). BCC authentication and rate-limit errors also include a code field (stable machine-readable identifier). Upstream validation errors may omit code.

{ "error": "Missing or invalid API key", "code": "UNAUTHORIZED" }

400 — invalid country code or invalid days parameter
401 — missing or invalid API key
403 — no active trial or paid access
404 — channel not found
429 — rate limit exceeded; check the Retry-After header
503 — upstream or configuration problem

Pricing · Playground