Sports operations

The sports namespace exposes the new Sports API — multi‑sport competition data (football,
basketball, tennis, …) with seasons, stages, groups and standings.

Responses are cached and enriched automatically:

• Cached with a stale‑while‑revalidate strategy — repeat reads are served instantly from a local
  cache (browser: IndexedDB; server: in‑memory; React Native: AsyncStorage) and refreshed in the
  background, so live standings stay up to date without extra round‑trips. The cache TTL is the value
  configured for your client in the Management Portal (Features → Cache TTL).
• Enriched — each competition is returned with its descriptive metadata (name, branding,
  assets, …), each stage with its resolved stage name, and each standing with its resolved
  competitor (team / athlete / national team). Text fields (name, shortName) are localized to
  the lang you configured (see Configuration).

getCompetitionById

Returns a single competition with its season, stages, groups and standings.

sdk.sports.getCompetitionById(
  competitionId: string,
  filters?: CompetitionByIdFilters,
  disableCache?: boolean,
): Promise<CompetitionModel>

Parameters

CompetitionByIdFilters

Example

import { FansUnitedSDK } from "fansunited-js-sdk";

const sdk = FansUnitedSDK({
  apiKey: "<API_KEY>",
  clientId: "<CLIENT_ID>",
  idSchema: "native",
  lang: "en",
});

// Current season
const competition = await sdk.sports.getCompetitionById("fb:c:1");

console.log(competition.name); // "First Professional League" (localized to `lang`)

const stage = competition.season?.stages?.[0];
console.log(stage?.stageNameModel?.name); // "Regular Season"

const standings = stage?.groups?.[0]?.standings ?? [];
standings.forEach((row) => {
  console.log(row.rank, row.competitorModel?.name); // 1 "Arda Kardzhali"
});

// A specific season
const past = await sdk.sports.getCompetitionById("fb:c:1", {
  seasonId: "fb:c:1:2024/25",
});

// Force a fresh response (skip both SDK and server cache)
const fresh = await sdk.sports.getCompetitionById("fb:c:1", undefined, true);

Response models

CompetitionModel

CompetitionMetaModel

SeasonModel

StageModel

GroupModel

StandingEntryModel

StandingStatModel

StageNameModel

CompetitorModel

Shared models

AssetModel — { key: string; value: string } (e.g. { key: "LOGO", value: "https://…png" }).

ProviderRefModel — { provider: string; id: string }.

RelatedModel — { relationship: string; relatedId: string }.

CompetitorMetadataModel — { branding: CompetitorBrandingModel | null }.

CompetitorBrandingModel — { primaryColor, secondaryColor, tertiaryColor: string | null }.

CompetitionEntityBrandingModel — { primaryColor, secondaryColor, textColor, backgroundColor, backgroundGradientFromColor, backgroundGradientToColor, backgroundImage: string | null; shirtColors: any[] }.

Caching notes

• The first call for a competition fetches from the network; subsequent calls within the TTL are
  served instantly from the local cache.
• Once the TTL lapses, the next call still returns instantly (from the cached copy) and refreshes in
  the background, so the following call has fresh data.
• Pass disableCache: true to force a fresh origin response (bypasses both the SDK cache and the
  server cache).
• To tune how long the enrichment entities (stage names, competitors, competitions) are cached, use
  the cache configuration option.