TV Listings — the raw guide

The staged broadcast schedule exactly as the official broadcaster sites publish it, any sport, one row per program slot. Unlike the fixture-linked broadcasts served under include=broadcasts (see the TV Broadcasts guide), this endpoint serves everything we stage — including listings that have no canonical fixture yet: a cycling stage on a sports channel, a Formula 1 session, a match in a competition whose fixtures are not imported. Nothing is guessed to make a row servable; each row is what one official site printed, with that site named in its provenance.

The one query most consumers need

GET /v3/tv/listings
    ?country=RO                  # ISO 3166-1 alpha-2
    &date_from=2026-07-06        # airs_at window (calendar days, UTC-bounded)
    &date_to=2026-07-12
    &per_page=100&page=1

Returns every staged listing for the country in the date window, soonest first. The horizon is what the broadcaster sites publish — the current week, refreshed by the daily import — so poll daily (or use updated_since for deltas) and the window rolls forward with you.

Filters

GET /v3/tv/listings?country=RO&program_type=live_event # real events only — no news/magazines/shopping
GET /v3/tv/listings?country=RO&sport=formula-1        # one sport
GET /v3/tv/listings?country=RO&match_status=unmatched  # linkable but unlinked
GET /v3/tv/listings?country=RO&match_status=rejected   # the AI-settled non-sport rows (excluded by default)
GET /v3/tv/listings?country=RO&updated_since=2026-07-06T12:00:00Z   # delta sync

match_status is the correlation lifecycle: matched rows carry matched_fixture_id (and the reconciled broadcast also appears on that fixture under include=broadcasts); unmatched/pending rows are real broadcasts we could not (or not yet) link to a fixture; no_pairing rows carry no team pairing (individual sports, events, magazines); rejected rows were judged non-sport content and are excluded by default — ask for them explicitly if you want the full raw feed.

Response shape

{
  "data": [
    {
      "id": "0197…",
      "country_name": "Romania",
      "tv_channel_id": "0197…",
      "tv_channel_name": "Antena 3 CNN",
      "airs_at": "2026-07-11T10:45:00.000Z",
      "ends_at": null,
      "title": "Cursă sprint Formula 1",
      "sport": "formula-1",
      "program_type": "live_event",
      "is_live": null,
      "home_name": null,
      "away_name": null,
      "competition_hint": null,
      "round": null,
      "leg": null,
      "match_status": "no_pairing",
      "matched_fixture_id": null,
      "source": "antena3",
      "is_official_source": true,
      "source_count": 1,
      "importance_score": 780,
      "importance_tier": "major",
      "importance_basis": "deterministic",
      "updated_at": "2026-07-06T09:12:44.000Z",
      "confidence": 700,
      "provenance": {
        "decided_by": "single_source",
        "sources": ["antena3"],
        "observation_ids": [],
        "is_derived": false,
        "reconciled_at": "2026-07-06T09:12:44.000Z"
      }
    }
  ],
  "meta": { "pagination": { "page": 1, "per_page": 100, "total": 402, "total_pages": 5 } }
}

What the fields mean

title is the program title verbatim from the broadcaster’s site; home_name/away_name/competition_hint are what our parser extracted from it (source spelling, e.g. “Portugalia”), null when the title carries none. round and legare the stage phrase and leg number when the title states them (“Preliminarii, tur 1”, “returul”). program_type says what KIND of program the slot is — live_event for actual event coverage (matches, races, stages), versus replay, highlights, studio_magazine, news, and shopping; null while still unclassified. airs_atis UTC, converted from the schedule’s local time across DST. is_live is true only on an explicit live marker, false on a replay, null when the site says nothing.

importance_score (0–1000) and importance_tier (marquee/major/notable/minor) rank how big the event is, and importance_basis says how that was decided (deterministic from the competition/round/teams, or ai_consensus/blended when a recognised competition was missing and an AI consensus lifted it). These are only populated for live_event rows and are the same numbers the What’s On feed ranks by — if you only want the curated, deduped, ranked live events, use that endpoint instead of filtering this one yourself.

Trust, honestly stated

These are staging rows, not reconciled records — but corroboration is counted honestly: when the same event (same team pairing, same calendar date) appears on several independent guide sites, source_count rises above 1, provenance.sources names every corroborating site, and confidenceis raised above the single source’s broadcast trust (capped below the reconciled multi-source tier). A single-source row keeps its source’s explicit trust (official broadcaster sites sit at the 700 tier). When you need the fully reconciled, fixture-linked record, use the fixture’s include=broadcasts instead; a matched listing gives you the fixture id to join on.

A practical import recipe

Pull the window daily per country, upsert on id, and treat updated_at as the change signal (titles change, matches link, statuses settle — re-scrapes re-open changed slots automatically). Rows can disappear when a broadcaster moves a slot (the superseded row is deleted), so a full-window pull is the simplest way to stay consistent; updated_since catches everything else between pulls.