Football Data API Client

A comprehensive TypeScript client for interacting with football data APIs. This package provides easy access to competitions, matches, teams, and player data with strongly typed responses.

Features

• 🏆 Complete football data: Access competitions, matches, teams, players, and more
• 📊 Strongly typed: Written in TypeScript with full type definitions
• 🚀 Simple API: Intuitive methods following REST principles
• 🔄 Flexible parameters: Customize requests with filtering, sorting, and pagination
• 📱 Lightweight: Minimal dependencies for better performance

Installation

npm install football-data-api-client

or using yarn:

yarn add football-data-api-client

Getting Started

First, import the client and initialize it with your API key:

import { FootballDataClient } from 'football-data-api-client';

const client = new FootballDataClient({
  apiKey: 'YOUR_API_KEY', 
  // optional configuration
  baseUrl: 'https://api.football-data.org/v4', // default
  timeout: 10000 // 10 seconds (default)
});

GET API KEY

https://www.football-data.org/

Usage

The client provides access to four main resources:

• Competitions
• Matches
• Teams
• Players

Each resource provides methods to interact with the respective endpoints.

Competitions

Access competition data, standings, scorers and more:

// Get list of available competitions
const competitions = await client.competitions.list();

// Get a specific competition by ID
const premierLeague = await client.competitions.get({ id: 2021 });

// Get competition standings
const standings = await client.competitions.getStandings(2021);

// Get top scorers from a competition
const scorers = await client.competitions.getScorers(2021, 10); // Limit to top 10

// Get competition matches with filters
const matches = await client.competitions.getMatches(2021, {
  dateFrom: '2023-08-01',
  dateTo: '2023-08-31',
  status: 'FINISHED'
});

// Get teams participating in a competition
const teams = await client.competitions.getTeams(2021);

// Get matchday information
const matchday = await client.competitions.getMatchday(2021, { current: true });

Matches

Retrieve match data, statistics, lineups and more:

// Get list of matches with optional filters
const matches = await client.matches.list({
  dateFrom: '2023-09-01',
  dateTo: '2023-09-30',
  competitions: '2021,2014' // Premier League and La Liga
});

// Get details of a specific match
const match = await client.matches.get({ id: 327123 });

// Get today's matches
const todayMatches = await client.matches.getToday();

// Get matches from a specific competition
const competitionMatches = await client.matches.getByCompetition(2021, {
  matchday: 5,
  season: '2023'
});

// Get head-to-head matches between two teams
const headToHead = await client.matches.getHeadToHead(5, 65, 10); // Limit to 10 matches

// Get matches of a specific team
const teamMatches = await client.matches.getByTeam(5, {
  dateFrom: '2023-01-01',
  status: 'FINISHED'
});

// Get matches by status
const liveMatches = await client.matches.getByStatus('LIVE');

// Get upcoming matches
const upcomingMatches = await client.matches.getUpcoming(5); // Next 5 matches

// Get recently finished matches
const finishedMatches = await client.matches.getFinished(10); // Last 10 matches

// Get live matches
const liveMatches = await client.matches.getLive();

// Get match statistics
const matchStats = await client.matches.getStatistics(327123);

// Get match events (goals, cards, substitutions)
const matchEvents = await client.matches.getEvents(327123);

// Get match lineups
const lineups = await client.matches.getLineups(327123);

// Get matches for a specific date
const dateMatches = await client.matches.getByDate('2023-10-05');

// Get matches for a date range
const rangeMatches = await client.matches.getByDateRange('2023-10-01', '2023-10-15');

Teams

Access team data, players, fixtures, statistics and more:

// Get list of teams with optional filters
const teams = await client.teams.list({
  name: 'United',
  limit: 10
});

// Get details of a specific team
const team = await client.teams.get({ id: 57 });

// Get team matches
const teamMatches = await client.teams.getMatches(57, {
  status: 'SCHEDULED',
  venue: 'HOME',
  limit: 5
});

// Get team's full squad
const squad = await client.teams.getSquad(57);

// Get teams participating in a competition
const competitionTeams = await client.teams.getByCompetition(2021, '2023');

// Search teams by name
const searchResults = await client.teams.search('Arsenal', 5);

// Get upcoming matches
const upcomingMatches = await client.teams.getUpcomingMatches(57, 5);

// Get recent matches
const recentMatches = await client.teams.getLastMatches(57, 5);

// Get team statistics
const stats = await client.teams.getStatistics(57, {
  competition: 2021,
  season: '2023'
});

// Get team transfers
const transfers = await client.teams.getTransfers(57);

// Get team trophies/honors
const trophies = await client.teams.getTrophies(57);

// Get teams by country
const englishTeams = await client.teams.getByCountry('England', 20);

// Get teams by city
const londonTeams = await client.teams.getByCity('London', 10);

// Get team fixtures (schedule)
const fixtures = await client.teams.getFixtures(57, '2023');

// Get team standings in competitions
const standings = await client.teams.getStandings(57, '2023');

Players

Retrieve player information, statistics, matches and more:

// Get player details
const player = await client.players.get({ id: 44 });

// Get player matches
const playerMatches = await client.players.getMatches(44, {
  status: 'FINISHED',
  limit: 10
});

// Search players by name
const searchResults = await client.players.search('Messi', 5);

// Get player statistics
const stats = await client.players.getStatistics(44, {
  competition: 2021,
  season: '2023'
});

// Get players from a specific team
const teamPlayers = await client.players.getByTeam(57);

// Get player transfer history
const transfers = await client.players.getTransfers(44);

// Get player trophies/honors
const trophies = await client.players.getTrophies(44);

// Get players by nationality
const frenchPlayers = await client.players.getByNationality('France', 20);

// Get players by position
const goalkeepers = await client.players.getByPosition('Goalkeeper', 10);

// Get players by age range
const youngPlayers = await client.players.getByAge(18, 23, 15);

// Get player goal statistics
const goalStats = await client.players.getGoalStatistics(44, {
  competition: 2021
});

// Get player contract history
const contracts = await client.players.getContractHistory(44);

API Reference

Client Configuration

The client constructor accepts the following options:

interface ClientOptions {
  apiKey: string;         // Your API key (required)
  baseUrl?: string;       // Default: 'https://api.football-data.org/v4'
  timeout?: number;       // Request timeout in ms (default: 30000)
  headers?: Record<string, string>; // Additional HTTP headers
}

Resource Types

Each resource has corresponding TypeScript interfaces for parameters and responses:

Competition Types

interface Competition {
  id: number;
  name: string;
  code: string;
  type: string;
  emblem: string;
  // ...other fields
}

interface CompetitionListParams {
  areas?: string | number[];
  plan?: string;
  limit?: number;
}

interface CompetitionDetailParams {
  id: number | string;
}

interface CompetitionResponse {
  count: number;
  competitions: Competition[];
  // ...metadata
}

Match Types

interface Match {
  id: number;
  utcDate: string;
  status: string;
  matchday: number;
  stage: string;
  group: string | null;
  homeTeam: Team;
  awayTeam: Team;
  score: Score;
  // ...other fields
}

interface MatchListParams {
  competitions?: string | number[];
  dateFrom?: string;
  dateTo?: string;
  status?: string | string[];
  matchday?: number;
  group?: string;
  teams?: string | number[];
  limit?: number;
  // ...other filters
}

interface MatchDetailParams {
  id: number | string;
}

interface MatchResponse {
  count: number;
  matches: Match[];
  // ...metadata
}

Team Types

interface Team {
  id: number;
  name: string;
  shortName: string;
  tla: string;
  crest: string;
  address: string;
  website: string;
  founded: number;
  clubColors: string;
  venue: string;
  // ...other fields
}

interface TeamListParams {
  name?: string;
  areas?: string | number[];
  limit?: number;
}

interface TeamDetailParams {
  id: number | string;
}

interface TeamResponse {
  count: number;
  teams: Team[];
  // ...metadata
}

Player Types

interface Player {
  id: number;
  name: string;
  firstName: string;
  lastName: string;
  dateOfBirth: string;
  nationality: string;
  position: string;
  shirtNumber: number;
  // ...other fields
}

interface PlayerDetailParams {
  id: number | string;
}

interface PlayerResponse {
  count: number;
  players: Player[];
  // ...metadata
}

Error Handling

The client throws standardized errors for different types of API failures:

try {
  const data = await client.competitions.list();
} catch (error) {
  if (error.status === 401) {
    console.error('Authentication failed. Check your API key.');
  } else if (error.status === 403) {
    console.error('Access denied. Your subscription may not include this resource.');
  } else if (error.status === 429) {
    console.error('Rate limit exceeded. Slow down your requests.');
  } else {
    console.error('API error:', error.message);
  }
}

Rate Limiting

The API enforces rate limits depending on your subscription. The client doesn't implement automatic retry mechanisms, so you may need to handle rate limiting in your application.

Authentication

This client requires an API key from a football data provider. Sign up at the provider's website to obtain your API key.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

If you encounter any issues or have questions about using this package, please open an issue on GitHub.