@zafronix/football-sdk

A small, typed TypeScript client for the Zafronix Sports APIs — 29 football competitions (World Cup, Champions League, the top-5 European leagues and their cups, and more), the cross-competition entity APIs (player careers, referee analytics, club honours), and the AI-native surfaces: natural-language ask, semanticSearch, and the resolve identity join layer. One key works across everything.

Zero dependencies. Uses the global fetch (Node 18+, Bun, Deno, or the browser).

Install

npm install @zafronix/football-sdk

Get a free API key at https://api.zafronix.com/signup.

Quick start

import { ZafronixFootball } from '@zafronix/football-sdk';

const zfx = new ZafronixFootball({ apiKey: process.env.ZAFRONIX_API_KEY! });

// Cross-competition player career (typed)
const { career } = await zfx.players.career('lionel-messi-1987');
console.log(career?.totalAppearances, career?.goals);

// Any competition, same shape
const wc2026 = await zfx.competition('world-cup').matches({ year: 2026 });
const table  = await zfx.competition('premier-league').standings();

// Referee analytics + club honours
const ref  = await zfx.referees.analytics('michael-oliver');
const club = await zfx.clubs.honours('real-madrid');

// Ask a question in plain English
const answer = await zfx.ask('Who has won more, Real Madrid or Barcelona?');
console.log(answer.answer);

API

Competitions

zfx.competitions;                                  // catalog: { slug, path, label, mode, format }[]
const c = zfx.competition('champions-league');     // by slug or path
await c.tournaments();
await c.tournament(2024);
await c.matches({ year: 2024, stage: 'final' });
await c.teams();
await c.team('Real Madrid');
await c.standings({ year: 2024, group: 'A' });     // leagues + group stages
await c.bracket({ year: 2024 });                   // knockout competitions
await c.players();
await c.search('Zidane');
await c.onThisDay('05-25');
await c.raw('/aggregates/champions');              // any endpoint under this competition

Footballer API — zfx.players

await zfx.players.search('messi', { limit: 10 });
await zfx.players.get('lionel-messi-1987');
await zfx.players.career('lionel-messi-1987');                 // → PlayerCareerResponse
await zfx.players.leaderboard({ by: 'goals', limit: 10 });     // 'goals' | 'appearances'
await zfx.players.records({ top: 5 });
await zfx.players.resolve({ externalId: 'wikidata:Q615' });    // or { name, born }

Referee API — zfx.referees

await zfx.referees.get('michael-oliver');
await zfx.referees.analytics('michael-oliver');                // → RefereeAnalyticsResponse
await zfx.referees.leaderboard({ by: 'finals', limit: 10 });   // 'matches' | 'finals'
await zfx.referees.resolve({ externalId: 'wikidata:Q794992' });

Club API — zfx.clubs

await zfx.clubs.get('real-madrid');
await zfx.clubs.honours('real-madrid');                        // → ClubHonoursResponse
await zfx.clubs.leaderboard({ limit: 10 });                    // most-decorated
await zfx.clubs.resolve({ name: 'Inter' });                    // any spelling variant

Cross-competition analytics — zfx.analytics

await zfx.analytics.h2h('Real Madrid', 'Barcelona');
await zfx.analytics.teamRecord('Brazil');
await zfx.analytics.onThisDay('07-09');                        // defaults to today (UTC)

Natural language — zfx.ask

const r = await zfx.ask('How has Brazil performed across all competitions?');
r.interpreted.intent;   // 'team_record'
r.answer;               // one-line answer, grounded in the data
r.data;                 // the structured result

Semantic search — zfx.semanticSearch

Meaning-based discovery of the right competition, endpoint, or capability.

const s = await zfx.semanticSearch('European club knockout tournament');
s.results[0].title;     // 'UEFA Champions League API'
// Narrow by kind + cap results:
await zfx.semanticSearch('penalty shootout details', { type: 'endpoint', limit: 3 });

Identity join layer — zfx.resolve

Turn any external id (Wikidata / FBref / Transfermarkt), a Zafronix id, or a name into the right entity — player, club, or referee — with its cross-walk ids, the competitions it appears across, and links to the full record. Bring the id you already have, get ours.

const m = await zfx.resolve({ wikidata: 'Q615' });
m.match.type;           // 'player'
m.match.name;           // 'Lionel Messi'
m.match.externalIds;    // { wikidata: 'Q615', fbref: 'd70ce98e', transfermarkt: '28003' }
m.match.links.career;   // full-record URL

await zfx.resolve({ fbref: '53a2f082' });                 // → Real Madrid (club)
await zfx.resolve({ name: 'Collina', type: 'referee' });  // disambiguate a name

Errors

Non-2xx responses throw a ZafronixApiError with status, url, and the parsed body:

import { ZafronixApiError } from '@zafronix/football-sdk';
try {
  await zfx.players.get('nobody');
} catch (e) {
  if (e instanceof ZafronixApiError) console.error(e.status, e.message);
}

Notes

• One key, every API. The same key works across all competitions and entity APIs. The daily request cap is shared. See pricing.
• Goals in player/records endpoints count competitions Zafronix covers (tournaments + club cups); domestic-league scorer data isn't in the source.
• Full REST reference: api.zafronix.com/docs. Try endpoints live in the playground.

MIT © Zafronix LLC