api

Documentation

Overview

Package api defines structs and functions for requesting API-Football enpoints.

Index

• Constants
• type Client
  • func NewClient(subType SubscriptionType) *Client
  • func (c *Client) Countries(ctx context.Context, params *CountriesQueryParams) (*CountriesResult, error)
  • func (c *Client) Fixtures(ctx context.Context, params *FixturesQueryParams) (*FixturesResult, error)
  • func (c *Client) Leagues(ctx context.Context, params *LeaguesQueryParams) (*LeaguesResult, error)
  • func (c *Client) String() string
  • func (c *Client) TeamsInformation(ctx context.Context, params *TeamsInformationQueryParams) (*TeamsInformationResult, error)
  • func (c *Client) WithCustomAPIURL(url string) *Client
  • func (c *Client) WithCustomLogger(logger *slog.Logger) *Client
• type ClientError
• type CountriesQueryParams
• type CountriesResult
• type Country
• type Coverage
• type FieldValidationError
  • func (e *FieldValidationError) Error() string
• type Fixture
• type FixtureEventType
• type FixtureGoals
• type FixtureInfo
• type FixtureLeagueInfo
• type FixtureLineupsType
• type FixtureScore
• type FixtureStatisticsType
• type FixtureStatus
• type FixtureStatusType
• type FixtureTeam
• type FixtureTeams
• type FixtureVenue
• type FixturesCoverage
• type FixturesQueryParams
• type FixturesResult
• type League
• type LeagueInfo
• type LeagueTypeParam
• type LeaguesQueryParams
• type LeaguesResult
• type Periods
• type ResponseError
  • func (e *ResponseError) Error() string
• type ResponseOK
• type SeasonInfo
• type SubscriptionType
• type Team
• type TeamInformation
• type TeamsInformationQueryParams
• type TeamsInformationResult
• type UnknownHTTPCodeError
  • func (e *UnknownHTTPCodeError) Error() string
• type Venue

Constants

const (

	// FixtureStatusTBD : Time To Be Defined.
	FixtureStatusTBD FixtureStatusType = "TBD"
	// FixtureStatusNS : Not Started.
	FixtureStatusNS FixtureStatusType = "NS"
	// FixtureStatus1H : First Half, Kick Off.
	FixtureStatus1H FixtureStatusType = "1H"
	// FixtureStatusHT : Halftime.
	FixtureStatusHT FixtureStatusType = "HT"
	// FixtureStatus2H : Second Half, 2nd Half Started.
	FixtureStatus2H FixtureStatusType = "2H"
	// FixtureStatusET : Extra Time.
	FixtureStatusET FixtureStatusType = "ET"
	// FixtureStatusP : Penalty In Progress.
	FixtureStatusP FixtureStatusType = "P"
	// FixtureStatusFT : Match Finished.
	FixtureStatusFT FixtureStatusType = "FT"
	// FixtureStatusAET : Match Finished After Extra Time.
	FixtureStatusAET FixtureStatusType = "AET"
	// FixtureStatusPEN : Match Finished After Penalty.
	FixtureStatusPEN FixtureStatusType = "PEN"
	// FixtureStatusBT : Break Time (in Extra Time).
	FixtureStatusBT FixtureStatusType = "BT"
	// FixtureStatusSUSP : Match Suspended.
	FixtureStatusSUSP FixtureStatusType = "SUSP"
	// FixtureStatusINT : Match Interrupted.
	FixtureStatusINT FixtureStatusType = "INT"
	// FixtureStatusPST : Match Postponed.
	FixtureStatusPST FixtureStatusType = "PST"
	// FixtureStatusCANC : Match Cancelled.
	FixtureStatusCANC FixtureStatusType = "CANC"
	// FixtureStatusABD : Match Abandoned.
	FixtureStatusABD FixtureStatusType = "ABD"
	// FixtureStatusAWD : Technical Loss.
	FixtureStatusAWD FixtureStatusType = "AWD"
	// FixtureStatusWO : WalkOver.
	FixtureStatusWO FixtureStatusType = "WO"
	// FixtureStatisticsTypeShotsOnGoal : "Shots on Goal".
	FixtureStatisticsTypeShotsOnGoal FixtureStatisticsType = "Shots on Goal"
	// FixtureStatisticsTypeShotsOffGoal : "Shots off Goal".
	FixtureStatisticsTypeShotsOffGoal FixtureStatisticsType = "Shots off Goal"
	// FixtureStatisticsTypeTotalShots : "Total Shots".
	FixtureStatisticsTypeTotalShots FixtureStatisticsType = "Total Shots"
	// FixtureStatisticsTypeBlockedShots : "Blocked Shots".
	FixtureStatisticsTypeBlockedShots FixtureStatisticsType = "Blocked Shots"
	// FixtureStatisticsTypeShotsInsidebox : "Shots insidebox".
	FixtureStatisticsTypeShotsInsidebox FixtureStatisticsType = "Shots insidebox"
	// FixtureStatisticsTypeShotsOutsidebox : "Shots outsidebox".
	FixtureStatisticsTypeShotsOutsidebox FixtureStatisticsType = "Shots outsidebox"
	// FixtureStatisticsTypeFouls : "Fouls".
	FixtureStatisticsTypeFouls FixtureStatisticsType = "Fouls"
	// FixtureStatisticsTypeCornerKicks : "Corner Kicks".
	FixtureStatisticsTypeCornerKicks FixtureStatisticsType = "Corner Kicks"
	// FixtureStatisticsTypeOffsides : "Offsides".
	FixtureStatisticsTypeOffsides FixtureStatisticsType = "Offsides"
	// FixtureStatisticsTypeBallPossession : "Ball Possession".
	FixtureStatisticsTypeBallPossession FixtureStatisticsType = "Ball Possession"
	// FixtureStatisticsTypeYellowCards : "Yellow Cards".
	FixtureStatisticsTypeYellowCards FixtureStatisticsType = "Yellow Cards"
	// FixtureStatisticsTypeRedCards : "Red Cards".
	FixtureStatisticsTypeRedCards FixtureStatisticsType = "Red Cards"
	// FixtureStatisticsTypeGoalkeeperSaves : "Goalkeeper Saves".
	FixtureStatisticsTypeGoalkeeperSaves FixtureStatisticsType = "Goalkeeper Saves"
	// FixtureStatisticsTypeTotalPasses : "Total passes".
	FixtureStatisticsTypeTotalPasses FixtureStatisticsType = "Total passes"
	// FixtureStatisticsTypePassesAccurate : "Passes accurate".
	FixtureStatisticsTypePassesAccurate FixtureStatisticsType = "Passes accurate"
	// FixtureStatisticsTypePassesPct : "Passes %".
	FixtureStatisticsTypePassesPct FixtureStatisticsType = "Passes %"
	// FixtureEventTypeGoal : event type goal.
	FixtureEventTypeGoal FixtureEventType = "goal"
	// FixtureEventTypeCard : event type card.
	FixtureEventTypeCard FixtureEventType = "card"
	// FixtureEventTypeSubst : event type substitution.
	FixtureEventTypeSubst FixtureEventType = "subst"
	// FixtureLineupsTypeFormation : event type formation.
	FixtureLineupsTypeFormation FixtureLineupsType = "formation"
	// FixtureLineupsTypeCoach : event type coach.
	FixtureLineupsTypeCoach FixtureLineupsType = "coach"
	// FixtureLineupsTypeStartXI : event type startxi.
	FixtureLineupsTypeStartXI FixtureLineupsType = "startxi"
	// FixtureLineupsTypeSubstitutes : event type substitutes.
	FixtureLineupsTypeSubstitutes FixtureLineupsType = "substitutes"
)

Types

type Client

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

Client represents the base client requester.

func NewClient

func NewClient(subType SubscriptionType) *Client

NewClient returns a ready-to-use *Client for making requests to the API.

func (*Client) Countries

func (c *Client) Countries(ctx context.Context, params *CountriesQueryParams) (*CountriesResult, error)

Countries is the main function to request the /countries endpoint. params *CountriesQueryParams can be passed as optional request parameters, nil is accepted if there are no parameters to provide.

func (*Client) Fixtures

func (c *Client) Fixtures(ctx context.Context, params *FixturesQueryParams) (*FixturesResult, error)

Fixtures is the main function to request the /fixtures endpoint. params *FixturesQueryParams can be passed as optional request parameters, nil is accepted if there are no parameters to provide.

func (*Client) Leagues

func (c *Client) Leagues(ctx context.Context, params *LeaguesQueryParams) (*LeaguesResult, error)

Leagues is the main function to request the /leagues endpoint. params *LeaguesQueryParams can be passed as optional request parameters, nil is accepted if there are no parameters to provide.

func (*Client) String

func (c *Client) String() string

func (*Client) TeamsInformation

func (c *Client) TeamsInformation(ctx context.Context, params *TeamsInformationQueryParams) (*TeamsInformationResult, error)

TeamsInformation is the main function to request the /teams endpoint. params *TeamsInformationQueryParams can be passed as optional request parameters, nil is accepted if there are no parameters to provide.

func (*Client) WithCustomAPIURL

func (c *Client) WithCustomAPIURL(url string) *Client

WithCustomAPIURL allow to bring a custom slog.Logger to the library.

func (*Client) WithCustomLogger

func (c *Client) WithCustomLogger(logger *slog.Logger) *Client

WithCustomLogger allow to bring a custom slog.Logger to the library.

type ClientError

type ClientError error

ClientError for any client-related error.

var ErrAPIKeyEmpty ClientError = fmt.Errorf("API Key must be non empty")

ErrAPIKeyEmpty is returns when no API key could be found.

type CountriesQueryParams

type CountriesQueryParams struct {
	Name   string `validate:"omitempty,min=1" url:"name,omitempty"`
	Code   string `validate:"omitempty,len=2" url:"code,omitempty"`
	Search string `validate:"omitempty,min=3" url:"search,omitempty"`
}

CountriesQueryParams represents the parameters to pass to the /countries endpoint. validate tags are for the go-playground/validator. url tags are for google/go-querystring. `validate:"omitempty," url:",omitempty"`.

type CountriesResult

type CountriesResult struct {
	*ResponseOK
	Countries []Country
}

CountriesResult wraps the api raw response as well as the list of countries.

type Country

type Country struct {
	Name string `json:"name"`
	Code string `json:"code"`
	Flag string `json:"flag"`
}

Country wraps basic information on the country.

type Coverage

type Coverage struct {
	Standings   bool             `json:"standings"`
	Players     bool             `json:"players"`
	TopScorers  bool             `json:"top_scorers"`
	TopAssists  bool             `json:"top_assists"`
	TopCards    bool             `json:"top_cards"`
	Injuries    bool             `json:"injuries"`
	Predictions bool             `json:"predictions"`
	Odds        bool             `json:"odds"`
	Fixtures    FixturesCoverage `json:"fixtures"`
}

Coverage wraps information on the league's season data coverage.

type FieldValidationError

type FieldValidationError struct {
	// contains filtered or unexported fields
}

FieldValidationError is returned when the expected format of a field is incorrect.

func (*FieldValidationError) Error

func (e *FieldValidationError) Error() string

type Fixture

type Fixture struct {
	FixtureInfo FixtureInfo       `json:"fixture"`
	LeagueInfo  FixtureLeagueInfo `json:"league"`
	Teams       FixtureTeams      `json:"teams"`
	Goals       FixtureGoals      `json:"goals"`
	Score       FixtureScore      `json:"score"`
}

Fixture wraps league top objects.

type FixtureEventType

type FixtureEventType string

FixtureEventType represents type of event for a fixture.

type FixtureGoals

type FixtureGoals struct {
	Home *int `json:"home"`
	Away *int `json:"away"`
}

FixtureGoals wraps basic information on the fixture's goals. Goals can be nil when related to a period that did not happen.

type FixtureInfo

type FixtureInfo struct {
	ID        int           `json:"id"`
	Referee   string        `json:"referee"`
	Timezone  string        `json:"timezone"`
	Date      time.Time     `json:"date"`
	Timestamp int           `json:"timestamp"`
	Periods   Periods       `json:"periods"`
	Venue     FixtureVenue  `json:"venue"`
	Status    FixtureStatus `json:"status"`
}

FixtureInfo wraps basic information on the fixture.

type FixtureLeagueInfo

type FixtureLeagueInfo struct {
	ID      int    `json:"id"`
	Name    string `json:"name"`
	Country string `json:"country"`
	Logo    string `json:"logo"`
	Flag    string `json:"flag"`
	Season  int    `json:"season"`
	Round   string `json:"round"`
}

FixtureLeagueInfo wraps basic information on the fixture's league.

type FixtureLineupsType

type FixtureLineupsType string

FixtureLineupsType represents type of linepus for a fixture.

type FixtureScore

type FixtureScore struct {
	Halftime  FixtureGoals `json:"halftime"`
	Fulltime  FixtureGoals `json:"fulltime"`
	Extratime FixtureGoals `json:"extratime"`
	Penalty   FixtureGoals `json:"penalty"`
}

FixtureScore wraps basic information on the fixture's league.

type FixtureStatisticsType

type FixtureStatisticsType string

FixtureStatisticsType represents type of statistics for a fixture.

type FixtureStatus

type FixtureStatus struct {
	Long    string
	Short   string
	Elapsed int
}

FixtureStatus represents the current status of the fixture.

type FixtureStatusType

type FixtureStatusType string

FixtureStatusType represents the status of the game.

type FixtureTeam

type FixtureTeam struct {
	ID     int    `json:"id"`
	Name   string `json:"name"`
	Logo   string `json:"logo"`
	Winner bool   `json:"winner"`
}

FixtureTeam wraps basic information on a fixture's team.

type FixtureTeams

type FixtureTeams struct {
	Home FixtureTeam `json:"home"`
	Away FixtureTeam `json:"away"`
}

FixtureTeams wraps basic information on the fixture's teams.

type FixtureVenue

type FixtureVenue struct {
	ID   int
	Name string
	City string
}

FixtureVenue wraps basic info about the fixture's venue.

type FixturesCoverage

type FixturesCoverage struct {
	Events             bool `json:"events"`
	Lineups            bool `json:"lineups"`
	StatisticsFixtures bool `json:"statistics_fixtures"`
	StatisticsPlayers  bool `json:"statistics_players"`
}

FixturesCoverage wraps specific information on fixtures coverage.

type FixturesQueryParams

type FixturesQueryParams struct {
	ID          int
	IDs         []int
	Live        bool
	LiveLeagues []int
	Date        time.Time
	League      int
	Season      int
	Team        int
	Last        int
	Next        int
	From        time.Time
	To          time.Time
	Round       string
	Status      FixtureStatusType
	Timezone    string
}

FixturesQueryParams represents the parameters to pass to the /fixtures endpoint.

type FixturesResult

type FixturesResult struct {
	*ResponseOK
	Fixtures []Fixture `json:"fixtures"`
}

FixturesResult wraps the api raw response as well as the list of leagues.

type League

type League struct {
	LeagueInfo LeagueInfo   `json:"league"`
	Country    Country      `json:"country"`
	Seasons    []SeasonInfo `json:"seasons"`
}

League wraps league top objects.

type LeagueInfo

type LeagueInfo struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
	Type string `json:"type"`
	Logo string `json:"logo"`
}

LeagueInfo wraps basic information on the league.

type LeagueTypeParam

type LeagueTypeParam string

LeagueTypeParam represent the type of the league.

const (

	// LeagueTypeParamLeague can be passed as query `Type` parameter to return only leagues championships.
	LeagueTypeParamLeague LeagueTypeParam = "league"
	// LeagueTypeParamCup can be passed as query `Type` parameter to return only cups.
	LeagueTypeParamCup LeagueTypeParam = "cup"
)

type LeaguesQueryParams

type LeaguesQueryParams struct {
	ID      int             `validate:"omitempty,gte=0" url:"id,omitempty"`
	Name    string          `validate:"omitempty,min=1" url:"name,omitempty"`
	Country string          `validate:"omitempty,min=1" url:"country,omitempty"`
	Code    string          `validate:"omitempty,len=2" url:"code,omitempty"`
	Season  int             `validate:"omitempty,gte=1000,lte=9999" url:"season,omitempty"`
	Team    int             `validate:"omitempty,gte=0" url:"team,omitempty"`
	Type    LeagueTypeParam `validate:"omitempty" url:"type,omitempty"`
	Current bool            `validate:"omitempty" url:"current,omitempty"`
	Search  string          `validate:"omitempty,min=3" url:"search,omitempty"`
	Last    int             `validate:"omitempty,lte=99" url:"last,omitempty"`
}

LeaguesQueryParams represents the parameters to pass to the /leagues endpoint. validate tags are for the go-playground/validator. url tags are for google/go-querystring. `validate:"omitempty," url:",omitempty"`.

type LeaguesResult

type LeaguesResult struct {
	*ResponseOK
	Leagues []League `json:"leagues"`
}

LeaguesResult wraps the api raw response as well as the list of leagues.

type Periods

type Periods struct {
	First  int
	Second int
}

Periods represents timestamp for first and second period.

type ResponseError

type ResponseError struct {
	Message string `json:"message"`
}

ResponseError represents an invalid response from the server.

func (*ResponseError) Error

func (e *ResponseError) Error() string

type ResponseOK

type ResponseOK struct {
	Get        string         `json:"get"`
	Parameters map[string]any `json:"parameters"`
	Errors     map[string]any `json:"errors"`
	Results    int            `json:"results"`
	Paging     map[string]int `json:"paging"`
	Response   []byte         `json:"response"`
}

ResponseOK represents a valid response from the server.

type SeasonInfo

type SeasonInfo struct {
	Year     int      `json:"year"`
	Start    string   `json:"start"`
	End      string   `json:"end"`
	Current  bool     `json:"current"`
	Coverage Coverage `json:"coverage"`
}

SeasonInfo wraps basic information on the league's season.

type SubscriptionType

type SubscriptionType string

SubscriptionType is a custom type representing the subscription type to api-football.

const (
	// SubTypeAPISports is the api type if you subscribed to api-football through API Sports.
	SubTypeAPISports SubscriptionType = "APISports"
	// SubTypeRapidAPI is the api type if you subscribed to api-football through Rapid API.
	SubTypeRapidAPI SubscriptionType = "RapidAPI"
)

type Team

type Team struct {
	ID       int    `json:"id"`
	Name     string `json:"name"`
	Code     string `json:"code"`
	Country  string `json:"country"`
	Founded  int    `json:"founded"`
	National bool   `json:"national"`
	Logo     string `json:"logo"`
}

Team wraps basic information on the team.

type TeamInformation

type TeamInformation struct {
	Team  Team  `json:"team"`
	Venue Venue `json:"venue"`
}

TeamInformation wraps a team top objects.

type TeamsInformationQueryParams

type TeamsInformationQueryParams struct {
	ID      int    `validate:"omitempty,gte=0" url:"id,omitempty"`
	Name    string `validate:"omitempty,min=1" url:"name,omitempty"`
	Country string `validate:"omitempty,min=1" url:"country,omitempty"`
	Season  int    `validate:"omitempty,gte=1000,lte=9999" url:"season,omitempty"`
	Search  string `validate:"omitempty,min=3" url:"search,omitempty"`
	League  int    `validate:"omitempty,gte=0" url:"league,omitempty"`
	Code    string `validate:"omitempty,len=3" url:"code,omitempty"`
	Venue   int    `validate:"omitempty,gte=0" url:"venue,omitempty"`
}

TeamsInformationQueryParams is a struct for wrapping teams infos endpoint query parameters.

type TeamsInformationResult

type TeamsInformationResult struct {
	*ResponseOK
	Teams []TeamInformation `json:"teams"`
}

TeamsInformationResult wraps the api raw response as well as the list of teams.

type UnknownHTTPCodeError

type UnknownHTTPCodeError struct {
	// contains filtered or unexported fields
}

UnknownHTTPCodeError is returned when the http code can not be handled.

func (*UnknownHTTPCodeError) Error

func (e *UnknownHTTPCodeError) Error() string

type Venue

type Venue struct {
	ID       int    `json:"id"`
	Name     string `json:"name"`
	Address  string `json:"address"`
	City     string `json:"city"`
	Capacity int    `json:"capacity"`
	Surface  string `json:"surface"`
	Image    string `json:"image"`
}

Venue wraps basic information on the team's venue.