client

package module
v1.1.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 21, 2025 License: MIT Imports: 10 Imported by: 0

README

Go Report Card GoDoc

API Football Go Client

A simple, intuitive, and comprehensive Go client library for interacting with the API-Football service. This library allows you to easily retrieve data about leagues, teams, players, fixtures, transfers, and much more.

Note: This client is designed with ease-of-use and flexibility in mind. It’s fully open source, well-documented, and built for developers who want to integrate API-Football data into their Go applications. Contributions, feedback, and improvements are welcome!

Features

  • Clean & Simple API: Access various endpoints (Coachs, Fixtures, Injuries, Leagues, Players, Standings, Teams, Transfers, Trophies, Venues, etc.) with intuitive methods.
  • Dynamic Query Parameters: Pass custom filters and options via maps for flexible querying.
  • Customizable HTTP Client: Inject your own http.Client for advanced configurations or testing purposes.
  • Robust Error Handling: Clear error messages with wrapped errors to simplify debugging.
  • Comprehensive Documentation: Inline comments and examples to help you get started quickly.

Installation

Use go get to install the package:

go get github.com/0ffsideCompass/api-football-go-client

Or add it to your go.mod file:

require github.com/0ffsideCompass/api-football-go-client vX.Y.Z

Replace vX.Y.Z with the current version.

Quick Start

Here’s a simple example to get you started:

package main

import (
    "fmt"
    "log"
    "net/http"
    "time"

    "github.com/0ffsideCompass/api-football-go-client/client"
)

func main() {
    // Replace with your API key
    apiKey := "YOUR_API_KEY_HERE"

    // Create a new client using the default domain
    cli, err := client.New(apiKey, &http.Client{Timeout: 10 * time.Second})
    if err != nil {
        log.Fatalf("Error creating client: %v", err)
    }

    // Example: Fetch leagues for the 2020 season in England
    params := map[string]interface{}{
        "season":  2020,
        "country": "England",
    }
    leagues, err := cli.Leagues(params)
    if err != nil {
        log.Fatalf("Error fetching leagues: %v", err)
    }

    fmt.Printf("Leagues: %+v\n", leagues)
}

Endpoints Documentation

This client supports multiple endpoints. Below is an overview of some key methods:

Coachs
  • Description: Retrieves coach information.
  • Parameters: One or more of team, id, or search (with search requiring at least 3 characters).
Fixtures
  • Methods:
    • Fixture – Get fixtures with flexible filtering (by id, league, season, date, etc.).
    • FixturesLineups – Get lineups for a given fixture.
    • FixturesEvents – Retrieve events for a fixture.
    • FixtureHeadToHead – Get head-to-head stats between teams.
    • FixtureByDateAndLeague – Get fixtures by date range and league.
    • FixtureStatistics – Retrieve statistics for a fixture.
    • FixturesPlayer – Get player data for a fixture.
Injuries
  • Description: Retrieves injury reports.
  • Validation: Ensures that if league, team, or player is provided, then season is required.
Leagues
  • Description: Retrieves league information with filters for id, name, season, country, etc.
Players
  • Description: Retrieve player details, seasons, squads, and top performance metrics.
  • Methods:
    • PlayersSeasons
    • Players
    • PlayersSquads
    • PlayersTopScorers
    • PlayersTopAssists
    • PlayersTopYellowCards
    • PlayersTopRedCards
Standings
  • Description: Get league standings.
  • Parameters: Requires season and league (optionally team).
Teams
  • Description: Retrieves team data and statistics.
  • Methods:
    • Teams
    • TeamsStatistics
Transfers, Trophies, Venues
  • Description: Access data related to player transfers, trophies, and venue information.
  • Description: A generic search function for teams, leagues, or players.
  • Usage: Search(query string, t Type) where Type is one of Team, League, or Player.

For detailed usage of each method, refer to the inline comments within the code.

Contributing

Contributions are welcome! If you’d like to improve the client, please follow these guidelines:

  • Fork the repository and create a new branch for your feature or bug fix.
  • Ensure your code follows the existing style and documentation practices.
  • Add tests for any new functionality.
  • Open a pull request with a clear description of your changes.

License

This project is licensed under the MIT License.

Support

If you encounter issues or have questions, please open an issue on GitHub.

Happy coding and enjoy integrating API-Football data into your projects!

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

type Client struct {
	Domain string
	// contains filtered or unexported fields
}

Client represents a client for the API-Football service. It holds the API key, the base domain URL, and the underlying HTTP client used to execute requests.

func New 

func New(key string, client HttpClient) (*Client, error)

New creates a new Client instance for the API-Football service using the default domain. It returns an error if the API key is missing or the provided HTTP client is nil.

func NewWithDomain 

func NewWithDomain(key, domain string, client HttpClient) (*Client, error)

NewWithDomain creates a new Client instance with a custom domain. It returns an error if the API key is missing or the provided HTTP client is nil.

func (*Client) Coachs 

func (c *Client) Coachs(
	params map[string]interface{},
) (*models.Coachs, error)

Coachs hits the /coachs endpoint

  • team: (Type: integer) The ID of the team. Value format: 85
  • id: (Type: integer) The ID of the coach. Value format: 85
  • search: (Type: string) The name of the coach. Value format: "John Doe" must be >= 3 characters one of the following parameters must be passed

func (*Client) Fixture 

func (c *Client) Fixture(
	params map[string]interface{},
) (*models.FixturesResponse, error)

Fixture returns all fixtures for parameters passed

  • id: (Type: integer) The ID of the fixture. Value format: 43.
  • ids: (Type: strings) One or more fixture IDs. Value format: "id-id-id". Maximum of 20 fixture IDs.
  • live: (Type: string) Enumerated values:
  • "all": All leagues.
  • "id-id": Specific league IDs (this is a placeholder; handle dynamically based on IDs).
  • date: (Type: string) A valid date in the format YYYY-MM-DD.
  • league: (Type: integer) The ID of the league.
  • season: (Type: integer) (should be 4 digits) The season of the league. Format: 4 characters YYYY.
  • team: (Type: integer) The ID of the team.
  • last: (Type: integer) (<= 2 digis) For the X last fixtures. Value should be an integer with <= 2 characters.
  • next: (Type: integer) (<= 2 digis) For the X next fixtures. Value should be an integer with <= 2 characters.
  • from: (Type: string) A valid starting date for a date range. Format: YYYY-MM-DD.
  • to: (Type: string) A valid ending date for a date range. Format: YYYY-MM-DD.
  • round: (Type: string) The round of the fixture.
  • status: (Type: string) Enumerated values:
  • "NS": A specific fixture status.
  • "NS-PST-FT": Combined fixture statuses.
  • venue: (Type: integer) The venue ID of the fixture.

==================================================================================

func (*Client) FixtureByDateAndLeague 

func (c *Client) FixtureByDateAndLeague(
	leagueID,
	season int,
	fromDate time.Time,
	toDate time.Time,
) (*models.FixturesByDateResp, error)

FixtureByDateAndLeague returns all fixtures for a given date and league

func (*Client) FixtureHeadToHead 

func (c *Client) FixtureHeadToHead(
	params map[string]interface{},
) (*models.FixtureHeadToHeadResp, error)

FixtureHeadToHead returns head to head for two teams

  • h2h: (Type: string)(Required)(format id-id) The ids of the teams
  • date (Type: string)(format YYYY-MM-DD) The date of the match
  • league (Type: integer) The id of the league
  • season (Type: integer)(4 digits)(format YYYY) The season of the league
  • last (Type: integer) For the X last fixtures.
  • next (Type: integer) For the X next fixtures.
  • from (Type: string)(format YYYY-MM-DD) A valid starting date for a date range.
  • to (Type: string)(format YYYY-MM-DD) A valid ending date for a date range.
  • venue (Type: integer) The venue ID of the fixture.
  • status (Type: string) Enumerated values:
  • "NS": A specific fixture status.
  • "NS-PST-FT": Combined fixture statuses.

func (*Client) FixtureStatistics 

func (c *Client) FixtureStatistics(
	params map[string]interface{},
) (*models.FixturesStatisticsResponse, error)

FixtureStatistics returns statistics for a given fixture

  • fixture (Type: integer)(Required) The ID of the fixture. Value format: 43.
  • team (Type: integer) The ID of the team. Value format: 85.

func (*Client) FixturesEvents 

func (c *Client) FixturesEvents(
	params map[string]interface{},
) (*models.FixturesEventsResponse, error)

FixturesEvents returns all events for a given fixture

  • fixture: (Type: integer)(Required) The ID of the fixture. Value format: 43.
  • team: (Type: integer) The ID of the team. Value format: 85.
  • player: (Type: integer) The ID of the player. Value format: 85.

func (*Client) FixturesLineups 

func (c *Client) FixturesLineups(
	params map[string]interface{},
) (*models.FixturesLineupsResponse, error)

FixturesLineups returns lineups for a given fixture

  • fixture: (Type: integer)(Required) The ID of the fixture. Value format: 43.
  • team: (Type: integer) The ID of the team. Value format: 85.
  • player: (Type: integer) The ID of the player. Value format: 85.

func (*Client) FixturesPlayer 

func (c *Client) FixturesPlayer(
	params map[string]interface{},
) (*models.FixturesPlayersResponse, error)

FixturesPlayer returns fixture's player data

  • fixture (Type: integer)(Required) The ID of the fixture. Value format: 43.
  • team (Type: integer) The ID of the team. Value format: 85.

func (*Client) Injuries 

func (c *Client) Injuries(
	params map[string]interface{},
) (*models.InjuriesResponse, error)

Injuries hits the /injuries endpoint

  • league: (Type: integer) The ID of the league. Value format: 2

  • season: (Type: integer) (should be 4 digits) The year of the season. Value format: 2020

  • fixture: (Type: integer) The ID of the fixture. Value format: 157304

  • team: (Type: integer) The ID of the team. Value format: 85

  • player: (Type: integer) The ID of the player. Value format: 85

  • date: (Type: string) (format: YYYY-MM-DD) The date of the fixture. Value format: 2020-12-01

    if league is provided, season is required if team is provided, season is required if player is provided, season is required

func (*Client) Leagues 

func (c *Client) Leagues(
	params map[string]interface{},
) (*models.LeaguesResponse, error)

Leagues returns all leagues

  • id (Type: integer) The ID of the league. Value format: 2
  • name (Type: string) The name of the league. Value format: Premier League -country (Type: string) The name of the country. Value format: England
  • season (Type: integer) (should be 4 digits) The year of the season. Value format: 2020
  • team (Type: integer) The ID of the team. Value format: 85
  • type (Type: string) The type of the league. Value format: League
  • current (Type: string) Enum: (true, false) Return the list of active seasons or the last one of each competition. Value format: "true"
  • search (Type: string) (should be 3 characters or more) The name of the league. Value format: Premier League
  • last (Type: integer) (<= 2 digis) The X last leagues/cups added in the API
  • code (Type: string) (2 characters) The code of the country. Value format: FR

func (*Client) Players 

func (c *Client) Players(
	params map[string]interface{},
) (*models.PlayersResponse, error)

func (*Client) PlayersSeasons 

func (c *Client) PlayersSeasons(
	params map[string]interface{},
) (*models.PlayersSeasonsResponse, error)

PlayersSeasons returns the seasons for a given player

  • player (Type: integer) The ID of the player. Value format: 85

func (*Client) PlayersSquads 

func (c *Client) PlayersSquads(
	params map[string]interface{},
) (*models.PlayersSquadsResponse, error)

func (*Client) PlayersTopAssists 

func (c *Client) PlayersTopAssists(
	params map[string]interface{},
) (*models.PlayersTopResponse, error)

PlayersTopAssists returns the top assists for a given league and season

  • league (Type: integer)(Required) The ID of the league. Value format: 2
  • season (Type: integer)(Required) (4 digits) The year of the season. Value format: 2020

func (*Client) PlayersTopRedCards 

func (c *Client) PlayersTopRedCards(
	params map[string]interface{},
) (*models.PlayersTopResponse, error)

PlayersTopRedCards returns the top assists for a given league and season

  • league (Type: integer)(Required) The ID of the league. Value format: 2
  • season (Type: integer)(Required) (4 digits) The year of the season. Value format: 2020

func (*Client) PlayersTopScorers 

func (c *Client) PlayersTopScorers(
	params map[string]interface{},
) (*models.PlayersTopResponse, error)

PlayersTopScorers returns the top scorers for a given league and season

  • league (Type: integer)(Required) The ID of the league. Value format: 2
  • season (Type: integer)(Required) (4 digits) The year of the season. Value format: 2020

func (*Client) PlayersTopYellowCards 

func (c *Client) PlayersTopYellowCards(
	params map[string]interface{},
) (*models.PlayersTopResponse, error)

PlayersTopYellowCards returns the top assists for a given league and season

  • league (Type: integer)(Required) The ID of the league. Value format: 2
  • season (Type: integer)(Required) (4 digits) The year of the season. Value format: 2020

func (*Client) Search 

func (c *Client) Search(q string, t Type) ([]byte, error)

func (*Client) Sidelined 

func (c *Client) Sidelined(
	params map[string]interface{},
) (*models.SidelinedResponse, error)

func (*Client) Standings 

func (c *Client) Standings(
	params map[string]interface{},
) (*models.StandingsResponse, error)

Standings hits the /standings endpoint

  • season: (Type: integer) (Required) 4 characters YYYY The season of the standings. Value format: 2019
  • league: (Type: integer) (Required) The ID of the league. Value format: 43
  • team: (Type: integer) The ID of the team. Value format: 85

func (*Client) Teams 

func (c *Client) Teams(
	params map[string]interface{},
) (*models.TeamsResponse, error)

Teams hits the /teams endpoint 

-id: (Type: integer)
  The ID of the team. Value format: 85
- name: (Type: string)
  The name of the team. Value format: Arsenal
- league: (Type: integer)
  The ID of the league. Value format: 2
- season: (Type: integer) (should be 4 digits)
  The year of the season. Value format: 2020
- country: (Type: string)
  The name of the country. Value format: England
- code: (Type: string) (3 characters)
  The code of the team. Value format: ARS
- venue: (Type: integer)
  The ID of the venue. Value format: 18
- search: (Type: string) (should be 3 characters or more)
  The name of the team. Value format: Arsenal

At least one of the following parameters must be passed

func (*Client) TeamsStatistics 

func (c *Client) TeamsStatistics(
	params map[string]interface{},
) (*models.TeamsStatisticsResponse, error)

TeamsStatistics hits the /teams/statistics endpoint

  • league (Type: integer) (required) The ID of the league. Value format: 2
  • season (Type: integer) (required) (should be 4 digits) The year of the season. Value format: 2020
  • team (Type: integer) (required) The ID of the team. Value format: 85
  • date (Type: string) (format: YYYY-MM-DD) The limit date. Value format: 2020-12-01

func (*Client) Transfers 

func (c *Client) Transfers(
	params map[string]interface{},
) (*models.TransfersResponse, error)

Transfers hits the /transfers endpoint

  • player (Type: integer) The ID of the player. Value format: 85
  • team (Type: integer) The ID of the team. Value format: 85 At least one of the following parameters must be passed

func (*Client) Trophies 

func (c *Client) Trophies(
	params map[string]interface{},
) (*models.TrophiesResponse, error)

Trophies hits the /trophies endpoint

  • player: (Type: integer) The ID of the player. Value format: 85

  • coach: (Type: integer) The ID of the coach. Value format: 85

    At least one of the following parameters must be passed

func (*Client) Venues 

func (c *Client) Venues(
	params map[string]interface{},
) (*models.VenuesResponse, error)

Venues hits the /venues endpoint

At least one of the following parameters must be passed:

  • id: (Type: integer) The ID of the league. Value format: 4
  • name: (Type: string) The name of the league. Value format: "OAKA Stadium"
  • country: (Type: string) The name of the country. Value format: "Greece"
  • city: (Type: string) The name of the city. Value format: "Athens"
  • search (Type: string) The name of the venue. Value format: "OAKA Stadium" should be => 3 characters

type HttpClient 

type HttpClient interface {
	Do(req *http.Request) (*http.Response, error)
}

HttpClient is an interface that abstracts the http.Client's Do method, allowing for easier testing and customization.

type Type 

type Type string
const (
	Team   Type = "team"
	League Type = "league"
	Player Type = "player"
)

func (Type) String 

func (t Type) String() string

String method to return the string representation of Type

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.