football

README

football-data-sdk

football-data-sdk is a Go client library for accessing the Football Data API.

Successful queries return native Go structs.

Services

• Areas
• Competitions
• Matches
• Players
• Teams

Installation

football-data-sdk is compatible with modern Go releases in module mode, with Go installed:

go get github.com/matheus-tex/football-data-sdk

will resolve and add the package to the current development module, along with its dependencies.

Alternatively the same can be achieved if you use import in a package:

import "github.com/matheus-tex/football-data-sdk"

and run go get without parameters.

Usage

import "github.com/matheus-tex/football-data-sdk"

client := football.NewClient()

// list all competitions
competitions, err := client.Competitions.List(context.Background(), nil)

Some API methods have optional parameters that can be passed. For example:

client := github.NewClient(nil)

// list public matches for a player
filters := &football.PlayerFiltersOptions{Limit: "5"}
matches, err := client.Players.Matches(context.Background(), "1", filters)

Make sure to export the env FOOTBALL_API_TOKEN with your API_TOKEN.

License

This library is distributed under the MIT license found in the LICENSE file.

Documentation

Index

• Constants
• type Area
• type AreaList
• type AreaService
  • func (s *AreaService) Find(ctx context.Context, id string) (*Area, error)
  • func (s *AreaService) List(ctx context.Context) (*AreaList, error)
• type Bookings
• type Client
  • func NewClient(httpClient *http.Client) *Client
  • func (c *Client) Get(path string, params interface{}, v interface{}) ([]byte, error)
  • func (client *Client) GetHeaders() http.Header
• type Coach
• type Competition
• type CompetitionFiltersOptions
• type CompetitionList
• type CompetitionMatches
• type CompetitionMatchesFiltersOptions
• type CompetitionScorers
• type CompetitionScorersFiltersOptions
• type CompetitionService
  • func (s *CompetitionService) Find(ctx context.Context, id string) (*Competition, error)
  • func (s *CompetitionService) List(ctx context.Context, filters *CompetitionFiltersOptions) (*CompetitionList, error)
  • func (s *CompetitionService) Matches(ctx context.Context, id string, filters *CompetitionMatchesFiltersOptions) (*CompetitionMatches, error)
  • func (s *CompetitionService) Scorers(ctx context.Context, id string, filters *CompetitionScorersFiltersOptions) (*CompetitionScorers, error)
  • func (s *CompetitionService) Standings(ctx context.Context, id string, filters *CompetitionStandingsFiltersOptions) (*CompetitionStandings, error)
  • func (s *CompetitionService) Teams(ctx context.Context, id string, filters *CompetitionTeamsFiltersOptions) (*CompetitionTeams, error)
• type CompetitionStandings
• type CompetitionStandingsFiltersOptions
• type CompetitionTeams
• type CompetitionTeamsFiltersOptions
• type Goals
• type Head2Head
• type Match
• type MatchResponse
• type MatchService
  • func (s *MatchService) Find(ctx context.Context, id string) (*MatchResponse, error)
  • func (s *MatchService) List(ctx context.Context, filters *MatchesFiltersOptions) (*MatchesCompetition, error)
• type MatchesCompetition
• type MatchesFiltersOptions
• type Player
• type PlayerFiltersOptions
• type PlayerMatches
• type PlayerService
  • func (s *PlayerService) Find(ctx context.Context, id string) (*Player, error)
  • func (s *PlayerService) Matches(ctx context.Context, id string, filters *PlayerFiltersOptions) (*PlayerMatches, error)
• type Referees
• type Score
• type Scorer
• type Season
• type Standing
• type StandingType
• type Status
• type Substitutions
• type Table
• type Team
• type TeamMatches
• type TeamMatchesFiltersOptions
• type TeamService
  • func (s *TeamService) Find(ctx context.Context, id string) (*Team, error)
  • func (s *TeamService) Matches(ctx context.Context, id string, filters *TeamMatchesFiltersOptions) (*TeamMatches, error)
• type TeamStats
• type Time
• type Winner

Constants

const (
	APIURL = "https://api.football-data.org/v2"
)

Types

type Area

type Area struct {
	ID           int     `json:"id,omitempty"`
	Name         string  `json:"name,omitempty"`
	CountryCode  string  `json:"countryCode,omitempty"`
	EnsignUrl    string  `json:"ensignUrl,omitempty"`
	ParentAreaID int     `json:"parentAreaId,omitempty"`
	ParentArea   string  `json:"parentArea,omitempty"`
	ChildAreas   *[]Area `json:"childAreas,omitempty"`
}

Area represents data about a Area.

type AreaList

type AreaList struct {
	Count   int                    `json:"count,omitempty"`
	Filters map[string]interface{} `json:"filters,omitempty"`
	Areas   []Area                 `json:"areas,omitempty"`
}

AreaList represents a collection of Areas

type AreaService

type AreaService service

AreaService provides methods for accessing information about areas.

func (*AreaService) Find

func (s *AreaService) Find(ctx context.Context, id string) (*Area, error)

Find takes a Area ID and returns the corresponding Area for that ID. https://www.football-data.org/documentation/api

func (*AreaService) List

func (s *AreaService) List(ctx context.Context) (*AreaList, error)

List returns a collection of all areas. https://www.football-data.org/documentation/api

type Bookings

type Bookings struct {
	Minute int    `json:"minute,omitempty"`
	Team   Team   `json:"team,omitempty"`
	Player Player `json:"player,omitempty"`
	Card   string `json:"card,omitempty"`
}

type Client

type Client struct {
	BaseURL *url.URL

	// Services used for talking to different parts of the Football API.
	Areas        *AreaService
	Competitions *CompetitionService
	Matches      *MatchService
	Players      *PlayerService
	Teams        *TeamService
	// contains filtered or unexported fields
}

func NewClient

func NewClient(httpClient *http.Client) *Client

NewClient returns a new GitHub API client. If a nil httpClient is provided, a new http.Client will be used.

func (*Client) Get

func (c *Client) Get(path string, params interface{}, v interface{}) ([]byte, error)

Get performs a GET against the api

func (*Client) GetHeaders

func (client *Client) GetHeaders() http.Header

type Coach

type Coach struct {
	ID             int    `json:"id,omitempty"`
	Name           string `json:"name,omitempty"`
	CountryOfBirth string `json:"countryOfBirth,omitempty"`
	Nationality    string `json:"nationality,omitempty"`
}

type Competition

type Competition struct {
	ID                       int      `json:"id,omitempty"`
	Area                     Area     `json:"area,omitempty"`
	Name                     string   `json:"name,omitempty"`
	Code                     string   `json:"code,omitempty"`
	NumberOfAvailableSeasons int      `json:"numberOfAvailableSeasons,omitempty"`
	Plan                     string   `json:"plan,omitempty"`
	CurrentSeason            Season   `json:"currentSeason,omitempty"`
	Seasons                  []Season `json:"seasons,omitempty"`
	LastUpdated              string   `json:"lastUpdated,omitempty"`
}

Competition represents data about a Competition

type CompetitionFiltersOptions

type CompetitionFiltersOptions struct {
	Areas string `url:"areas,omitempty"`
	Plan  string `url:"plan,omitempty"`
}

type CompetitionList

type CompetitionList struct {
	Count        int                    `json:"count,omitempty"`
	Filters      map[string]interface{} `json:"filters,omitempty"`
	Competitions []Competition          `json:"competitions,omitempty"`
}

CompetitionList represents a collection of Competitions

type CompetitionMatches

type CompetitionMatches struct {
	Count       int                    `json:"count,omitempty"`
	Filters     map[string]interface{} `json:"filters,omitempty"`
	Competition Competition            `json:"competition,omitempty"`
	Matches     []Match                `json:"matches,omitempty"`
}

CompetitionTeams represents a collection of Matches for a competition

type CompetitionMatchesFiltersOptions

type CompetitionMatchesFiltersOptions struct {
	DateFrom string `json:"dateFrom,omitempty"`
	DateTo   string `json:"dateTo,omitempty"`
	Stage    string `json:"stage,omitempty"`
	Status   Status `json:"status,omitempty"`
	MatchDay string `json:"matchday,omitempty"`
	Group    string `json:"group,omitempty"`
	Season   string `json:"season,omitempty"`
}

type CompetitionScorers

type CompetitionScorers struct {
	Count       int                    `json:"count,omitempty"`
	Filters     map[string]interface{} `json:"filters,omitempty"`
	Competition Competition            `json:"competition,omitempty"`
	Season      Season                 `json:"season,omitempty"`
	Scorers     []Scorer               `json:"scorers,omitempty"`
}

CompetitionTeams represents a collection of Scorers for a competition

type CompetitionScorersFiltersOptions

type CompetitionScorersFiltersOptions struct {
	Limit string `json:"limit,omitempty"`
}

type CompetitionService

type CompetitionService service

CompetitionService provides methods for accessing information about Competition.

func (*CompetitionService) Find

func (s *CompetitionService) Find(ctx context.Context, id string) (*Competition, error)

Find takes a Competition ID and returns the corresponding Competition for that ID. https://www.football-data.org/documentation/api

func (*CompetitionService) List

func (s *CompetitionService) List(ctx context.Context, filters *CompetitionFiltersOptions) (*CompetitionList, error)

List returns a collection of all competitions. https://www.football-data.org/documentation/api

func (*CompetitionService) Matches

func (s *CompetitionService) Matches(ctx context.Context, id string, filters *CompetitionMatchesFiltersOptions) (*CompetitionMatches, error)

Teams takes a Competition ID and returns a collection of all matches for that competition. https://www.football-data.org/documentation/api

func (*CompetitionService) Scorers

func (s *CompetitionService) Scorers(ctx context.Context, id string, filters *CompetitionScorersFiltersOptions) (*CompetitionScorers, error)

Teams takes a Competition ID and returns a collection of all scorers for that competition. https://www.football-data.org/documentation/api

func (*CompetitionService) Standings

func (s *CompetitionService) Standings(ctx context.Context, id string, filters *CompetitionStandingsFiltersOptions) (*CompetitionStandings, error)

Teams takes a Competition ID and returns a collection of all standings for that competition. https://www.football-data.org/documentation/api

func (*CompetitionService) Teams

func (s *CompetitionService) Teams(ctx context.Context, id string, filters *CompetitionTeamsFiltersOptions) (*CompetitionTeams, error)

Teams takes a Competition ID and returns a collection of all teams for that competition. https://www.football-data.org/documentation/api

type CompetitionStandings

type CompetitionStandings struct {
	Filters     map[string]interface{} `json:"filters,omitempty"`
	Competition Competition            `json:"competition,omitempty"`
	Season      Season                 `json:"season,omitempty"`
	Standings   []Standing             `json:"standings,omitempty"`
}

CompetitionTeams represents a collection of Standings for a competition

type CompetitionStandingsFiltersOptions

type CompetitionStandingsFiltersOptions struct {
	StandingType StandingType `url:"standingType,omitempty"`
}

type CompetitionTeams

type CompetitionTeams struct {
	Count       int                    `json:"count,omitempty"`
	Filters     map[string]interface{} `json:"filters,omitempty"`
	Competition Competition            `json:"competition,omitempty"`
	Season      Season                 `json:"season,omitempty"`
	Teams       []Team                 `json:"teams,omitempty"`
}

CompetitionTeams represents a collection of Teams for a competition

type CompetitionTeamsFiltersOptions

type CompetitionTeamsFiltersOptions struct {
	Season string `url:"season,omitempty"`
	Stage  string `url:"stage,omitempty"`
}

type Goals

type Goals struct {
	Minute    int         `json:"minute,omitempty"`
	ExtraTime interface{} `json:"extraTime,omitempty"`
	Type      string      `json:"type,omitempty"`
	Team      Team        `json:"team,omitempty"`
	Scorer    Player      `json:"scorer,omitempty"`
	Assist    Player      `json:"assist,omitempty"`
}

type Head2Head

type Head2Head struct {
	NumberOfMatches int       `json:"numberOfMatches,omitempty"`
	TotalGoals      int       `json:"totalGoals,omitempty"`
	HomeTeam        TeamStats `json:"homeTeam,omitempty"`
	AwayTeam        TeamStats `json:"awayTeam,omitempty"`
}

type Match

type Match struct {
	ID            int             `json:"id,omitempty"`
	Competition   *Competition    `json:"competition,omitempty"`
	Season        *Season         `json:"season,omitempty"`
	UtcDate       string          `json:"utcDate,omitempty"`
	Status        string          `json:"status,omitempty"`
	Minute        interface{}     `json:"minute,omitempty"`
	Attendance    int             `json:"attendance,omitempty"`
	Venue         string          `json:"venue,omitempty"`
	Matchday      int             `json:"matchday,omitempty"`
	Stage         string          `json:"stage,omitempty"`
	Group         string          `json:"group,omitempty"`
	LastUpdated   string          `json:"lastUpdated,omitempty"`
	HomeTeam      *Team           `json:"homeTeam,omitempty"`
	AwayTeam      *Team           `json:"awayTeam,omitempty"`
	Score         *Score          `json:"score,omitempty"`
	Goals         []Goals         `json:"goals,omitempty"`
	Bookings      []Bookings      `json:"bookings,omitempty"`
	Substitutions []Substitutions `json:"substitutions,omitempty"`
	Referees      []Referees      `json:"referees,omitempty"`
}

Match represents data about a Match

type MatchResponse

type MatchResponse struct {
	Head2Head Head2Head `json:"head2head,omitempty"`
	Match     Match     `json:"match,omitempty"`
}

type MatchService

type MatchService service

AreaService provides methods for accessing information about matches.

func (*MatchService) Find

func (s *MatchService) Find(ctx context.Context, id string) (*MatchResponse, error)

Find takes a Match ID and returns the corresponding Match for that ID. https://www.football-data.org/documentation/api

func (*MatchService) List

func (s *MatchService) List(ctx context.Context, filters *MatchesFiltersOptions) (*MatchesCompetition, error)

List returns a collection of all Matches. https://www.football-data.org/documentation/api

type MatchesCompetition

type MatchesCompetition struct {
	Count   int                    `json:"count,omitempty"`
	Filters map[string]interface{} `json:"filters,omitempty"`
	Matches []Match                `json:"matches,omitempty"`
}

MatchesCompetition represents a collection of Matches for a competition

type MatchesFiltersOptions

type MatchesFiltersOptions struct {
	DateFrom     string `json:"dateFrom,omitempty"`
	DateTo       string `json:"dateTo,omitempty"`
	Status       string `json:"status,omitempty"`
	Competitions string `json:"competitions,omitempty"`
}

type Player

type Player struct {
	ID             int64  `json:"id,omitempty"`
	Name           string `json:"name,omitempty"`
	FirstName      string `json:"firstName,omitempty"`
	LastName       string `json:"lastName,omitempty"`
	DateOfBirth    string `json:"dateOfBirth,omitempty"`
	CountryOfBirth string `json:"countryOfBirth,omitempty"`
	Nationality    string `json:"nationality,omitempty"`
	Position       string `json:"position,omitempty"`
	ShirtNumber    int    `json:"shirtNumber,omitempty"`
	LastUpdated    string `json:"lastUpdated,omitempty"`
	Role           string `json:"role,omitempty"`
}

Player represents data about a Player

type PlayerFiltersOptions

type PlayerFiltersOptions struct {
	DateFrom     string `json:"dateFrom,omitempty"`
	DateTo       string `json:"dateTo,omitempty"`
	Status       string `json:"status,omitempty"`
	Competitions string `json:"competitions,omitempty"`
	Limit        int64  `json:"limit,omitempty"`
}

type PlayerMatches

type PlayerMatches struct {
	Count   int                    `json:"count,omitempty"`
	Filters map[string]interface{} `json:"filters,omitempty"`
	Player  Player                 `json:"player,omitempty"`
	Matches []Match                `json:"matches,omitempty"`
}

type PlayerService

type PlayerService service

PlayerService provides methods for accessing information about players.

func (*PlayerService) Find

func (s *PlayerService) Find(ctx context.Context, id string) (*Player, error)

Find takes a Player ID and returns the corresponding Player for that ID. https://www.football-data.org/documentation/api

func (*PlayerService) Matches

func (s *PlayerService) Matches(ctx context.Context, id string, filters *PlayerFiltersOptions) (*PlayerMatches, error)

Matches takes a Player ID and returns a collection of all matches for that Player. https://www.football-data.org/documentation/api

type Referees

type Referees struct {
	ID          int         `json:"id,omitempty"`
	Name        string      `json:"name,omitempty"`
	Nationality interface{} `json:"nationality,omitempty"`
}

type Score

type Score struct {
	Winner    string `json:"winner,omitempty"`
	Duration  string `json:"duration,omitempty"`
	FullTime  Time   `json:"fullTime,omitempty"`
	HalfTime  Time   `json:"halfTime,omitempty"`
	ExtraTime Time   `json:"extraTime,omitempty"`
	Penalties Time   `json:"penalties,omitempty"`
}

type Scorer

type Scorer struct {
	Player        Player `json:"player,omitempty"`
	Team          Team   `json:"team,omitempty"`
	NumberOfGoals int    `json:"numberOfGoals,omitempty"`
}

type Season

type Season struct {
	ID              int      `json:"id,omitempty"`
	StartDate       string   `json:"startDate,omitempty"`
	EndDate         string   `json:"endDate,omitempty"`
	CurrentMatchday int      `json:"currentMatchday,omitempty"`
	Winner          Winner   `json:"winner,omitempty"`
	AvailableStages []string `json:"availableStages,omitempty"`
}

type Standing

type Standing struct {
	Stage string      `json:"stage,omitempty"`
	Type  string      `json:"type,omitempty"`
	Group interface{} `json:"group,omitempty"`
	Table []Table     `json:"table,omitempty"`
}

type StandingType

type StandingType string

const (
	StandingTypeTotal StandingType = "TOTAL"
	StandingTypeHome  StandingType = "HOME"
	StandingTypeAway  StandingType = "AWAY"
)

type Status

type Status string

const (
	StatusScheduled Status = "SCHEDULED"
	StatusLive      Status = "LIVE"
	StatusInPlay    Status = "IN_PLAY"
	StatusPaused    Status = "PAUSED"
	StatusFinished  Status = "FINISHED"
	StatusPostPoned Status = "POSTPONED"
	StatusSuspended Status = "SUSPENDED"
	StatusCanceled  Status = "CANCELED"
)

type Substitutions

type Substitutions struct {
	Minute    int    `json:"minute,omitempty"`
	Team      Team   `json:"team,omitempty"`
	PlayerOut Player `json:"playerOut,omitempty"`
	PlayerIn  Player `json:"playerIn,omitempty"`
}

type Table

type Table struct {
	Position       int  `json:"position,omitempty"`
	Team           Team `json:"team,omitempty"`
	PlayedGames    int  `json:"playedGames,omitempty"`
	Won            int  `json:"won,omitempty"`
	Draw           int  `json:"draw,omitempty"`
	Lost           int  `json:"lost,omitempty"`
	Points         int  `json:"points,omitempty"`
	GoalsFor       int  `json:"goalsFor,omitempty"`
	GoalsAgainst   int  `json:"goalsAgainst,omitempty"`
	GoalDifference int  `json:"goalDifference,omitempty"`
}

type Team

type Team struct {
	ID                 int            `json:"id,omitempty"`
	Area               *Area          `json:"area,omitempty"`
	ActiveCompetitions *[]Competition `json:"activeCompetitions,omitempty"`
	Name               string         `json:"name,omitempty"`
	ShortName          string         `json:"shortName,omitempty"`
	Tla                string         `json:"tla,omitempty"`
	CrestURL           string         `json:"crestUrl,omitempty"`
	Address            string         `json:"address,omitempty"`
	Phone              string         `json:"phone,omitempty"`
	Website            string         `json:"website,omitempty"`
	Email              string         `json:"email,omitempty"`
	Founded            int            `json:"founded,omitempty"`
	ClubColors         string         `json:"clubColors,omitempty"`
	Venue              string         `json:"venue,omitempty"`
	Coach              *Coach         `json:"coach,omitempty"`
	Captain            *Player        `json:"captain,omitempty"`
	Squad              *[]Player      `json:"squad,omitempty"`
	Lineup             *[]Player      `json:"lineup,omitempty"`
	Bench              *[]Player      `json:"bench,omitempty"`
	LastUpdated        string         `json:"lastUpdated,omitempty"`
}

Team represents data about a Team

type TeamMatches

type TeamMatches struct {
	Count   int                    `json:"count,omitempty"`
	Filters map[string]interface{} `json:"filters,omitempty"`
	Matches []Match                `json:"matches,omitempty"`
}

TeamMatches represents a collection of Matches for a Team

type TeamMatchesFiltersOptions

type TeamMatchesFiltersOptions struct {
	DateFrom string `json:"dateFrom,omitempty"`
	DateTo   string `json:"dateTo,omitempty"`
	Status   string `json:"status,omitempty"`
	Venue    string `json:"venue,omitempty"`
	Limit    int64  `json:"limit,omitempty"`
}

type TeamService

type TeamService service

TeamService provides methods for accessing information about teams.

func (*TeamService) Find

func (s *TeamService) Find(ctx context.Context, id string) (*Team, error)

Find takes a Team ID and returns the corresponding Team for that ID. https://www.football-data.org/documentation/api

func (*TeamService) Matches

func (s *TeamService) Matches(ctx context.Context, id string, filters *TeamMatchesFiltersOptions) (*TeamMatches, error)

Matches takes a Team ID and returns a collection of all Matches for that Team. https://www.football-data.org/documentation/api

type TeamStats

type TeamStats struct {
	Wins   int `json:"wins,omitempty"`
	Draws  int `json:"draws,omitempty"`
	Losses int `json:"losses,omitempty"`
}

type Time

type Time struct {
	HomeTeam int `json:"homeTeam,omitempty"`
	AwayTeam int `json:"awayTeam,omitempty"`
}

type Winner

type Winner struct {
	ID        int    `json:"id,omitempty"`
	Name      string `json:"name,omitempty"`
	ShortName string `json:"shortName,omitempty"`
	TLa       string `json:"tla,omitempty"`
	CrestURL  string `json:"crestUrl,omitempty"`
}