What’s On — the curated feed

The short list a “where to watch the match” app actually wants: only live events broadcast in the country, one row per event (the same match on several channels collapses into a single row with all its channels), and ranked by importance so the biggest matches per category surface first. Where the raw TV Listings endpoint serves everything we stage (replays, studio shows, teleshopping, every other sport), this endpoint hides all of that and hands you the curated, deduped, ranked result.

The one query most consumers need

GET /v3/tv/whats-on
    ?country=RO                  # ISO 3166-1 alpha-2
    &date_from=2026-07-11        # airs_at window; omit for "now -> +4 days"
    &date_to=2026-07-12
    &per_page=50&page=1

Returns the ranked live events for the country, biggest match first within each day. Omit the dates and it defaults to a rolling now → +4 dayswindow (events that already kicked off are dropped, so it reads as a live “on now / coming up” feed). Poll daily, or use updated_since for deltas.

Filters

GET /v3/tv/whats-on?country=RO&sport=football          # one category
GET /v3/tv/whats-on?country=RO&min_importance=major    # only the big matches (tier name)
GET /v3/tv/whats-on?country=RO&min_importance=800      # or a 0..1000 floor
GET /v3/tv/whats-on?country=RO&updated_since=2026-07-11T12:00:00Z  # delta sync

sport narrows to one category (football, formula-1, tennis, basketball, rugby…). min_importance takes either a tier name (marquee, major, notable, minor) or a 0–1000 floor — ask for major and you get only the matches worth putting on a screen. program_type is fixed to live_event and AI-rejected non-sport content is always excluded, so there is nothing to filter out.

Response shape

{
  "data": [
    {
      "event_key": "2026-07-11|argentina|franta",
      "sport": "football",
      "competition": "Campionatul Mondial",
      "home_name": "Argentina",
      "away_name": "Franța",
      "title": "Fotbal Campionatul Mondial: Argentina - Franța",
      "kickoff": "2026-07-11T19:00:00.000Z",
      "program_type": "live_event",
      "importance_score": 930,
      "importance_tier": "marquee",
      "is_live": true,
      "round": "Finala",
      "leg": null,
      "channels": [
        { "tv_channel_id": "0197…", "name": "Antena 1", "is_streaming": false, "airs_at": "2026-07-11T19:00:00.000Z", "source": "antena1" },
        { "tv_channel_id": "0197…", "name": "Antena Play", "is_streaming": true, "airs_at": "2026-07-11T19:00:00.000Z", "source": "antena1" }
      ],
      "country_id": "0197…",
      "country_name": "Romania",
      "source_count": 2,
      "updated_at": "2026-07-11T08:00:00.000Z",
      "confidence": 812,
      "provenance": {
        "decided_by": "majority",
        "sources": ["antena1", "digisport"],
        "observation_ids": [],
        "is_derived": true,
        "reconciled_at": "2026-07-11T08:00:00.000Z"
      }
    }
  ],
  "meta": { "pagination": { "page": 1, "per_page": 50, "total": 38, "total_pages": 1 } }
}

What the fields mean

importance_tier is the headline signal: marquee (a World Cup or Champions League match, the national team, a Grand Slam / Formula 1 marquee), major (a top league, a Superliga fixture, an NBA or big tennis match), then notable and minor. importance_scoreis the 0–1000 number behind it, for your own sorting. This is a curation / rankingsignal, not a sports fact — we never invent a result or a lineup; importance is derived from the competition, round and teams (and, for competitions our table does not recognize, an AI consensus that can only lift a match up to the “major” band, never fabricate a marquee).

channels is every channel airing the event, each with is_streaming (a streaming feed vs a linear TV channel) and its own airs_at — a restaurant tunes to any of them. home_name/away_name are null for a pairless event (a Formula 1 race, a solo tennis/rugby listing with no parsed pairing) — use title to display those. event_key is a stable id for the event (null for a pairless event grouped by sport + day + title).

Trust, honestly stated

When the same event appears on several independent guide sites, source_count rises above 1, provenance.sources names every corroborating site, and confidenceis raised above a single source’s broadcast trust (capped below the reconciled multi-source tier — these are staged guide rows, not reconciled records). When you need the fully reconciled, fixture-linked broadcast, follow a matched listing’s fixture into include=broadcasts (see the TV Broadcasts guide).