pandascore

README

pandascore-go

PandaScore client for Go.

Status

⚠ This is still a new project and does not completely abstract all PandaScore APIs or games (yet). It also has a couple of open issues (see below).

Getting started

Installation

go get github.com/tmbrggmn/pandascore-go

Usage

TODO

Points of attention/improvement

• Getting all pages from the PandaScore API has been implemented with by unmarshalling the results from all requests into a single array of map[string]interface{} to avoid having to use reflect to merge structs (see execution.go). Not sure if this is the best way to tackle this problem 🤷♂

Integration tests

In order to run the integration tests you'll need to do 2 things:

1. Add your on .env file to the root of the project
2. Enable integration tests by enabling the integration build flag

To set the PandaScore access token, simple create a new .env file in the root of the project and add your PandaScore access token in the PANDASCORE_ACCESS_TOKEN variable. For example:

PANDASCORE_ACCESS_TOKEN=my_pandascore_access_token

Integration tests are marked with the integration build flag, so to run them we need to enable integration tests when running the test: go test -tags=integration

Documentation

Overview

Consume the PandaScore API in Go.

TODO look at errors and how they're returned; we should probably be using Wrap() and stuff but I don't fully understand how that works

Index

• Constants
• type Client
  • func New() *Client
  • func (c *Client) AccessToken(accessToken string) *Client
  • func (c *Client) GetAllLeagues(game Game) ([]League, error)
  • func (c *Client) GetAllRunningMatches(game Game) ([]Match, error)
  • func (c *Client) GetAllRunningSeries(game Game) ([]Series, error)
  • func (c *Client) GetAllUpcomingMatches(game Game) ([]Match, error)
  • func (c *Client) GetAllUpcomingMatchesBetween(game Game, beginning time.Time, until time.Time) ([]Match, error)
  • func (c *Client) GetAllUpcomingMatchesForSeries(game Game, seriesID int) ([]Match, error)
  • func (c *Client) Request(game Game, path string) *Request
• type Game
  • func (g Game) IsValid() bool
• type League
• type Match
• type MatchOpponent
• type Opponent
• type PandaScoreError
  • func (pse *PandaScoreError) Error() string
• type Request
  • func (r *Request) Filter(field string, value ...string) *Request
  • func (r *Request) Get(value interface{}) (Response, error)
  • func (r *Request) GetAll(value interface{}) (Response, error)
  • func (r *Request) Page(page int) *Request
  • func (r *Request) PageSize(size int) *Request
  • func (r *Request) Range(field string, lowerBound string, upperBound string) *Request
  • func (r *Request) Search(field string, value string) *Request
  • func (r *Request) Sort(field string, order Sorting) *Request
• type Response
  • func (r *Response) HasMore() bool
• type Series
• type Sorting
• type Videogame

Constants

const (
	// PandaScore API base URL
	BaseURL string = "api.pandascore.co"

	// Name of the environment variable that contains the PandaScore access token
	AccessTokenEnvironmentVariable string = "PANDASCORE_ACCESS_TOKEN"
)

Types

type Client

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

PandaScore client which is the primary entity.

func New

func New() *Client

Construct a new PandaScore client with the default URL.

By default, the PandaScore access token will be read from the environment variable defined in the AccessTokenEnvironmentVariable constant. You can set it afterwards, for example if there is not environment variable.

func (*Client) AccessToken

func (c *Client) AccessToken(accessToken string) *Client

Sets this client's PandaScore access token to the given value.

func (*Client) GetAllLeagues

func (c *Client) GetAllLeagues(game Game) ([]League, error)

Returns all known leagues for the given game.

func (*Client) GetAllRunningMatches

func (c *Client) GetAllRunningMatches(game Game) ([]Match, error)

Returns all running matches for the given game.

func (*Client) GetAllRunningSeries

func (c *Client) GetAllRunningSeries(game Game) ([]Series, error)

Returns all currently ongoing series for the given game.

func (*Client) GetAllUpcomingMatches

func (c *Client) GetAllUpcomingMatches(game Game) ([]Match, error)

Returns all upcoming matches for the given game.

func (*Client) GetAllUpcomingMatchesBetween

func (c *Client) GetAllUpcomingMatchesBetween(game Game, beginning time.Time, until time.Time) ([]Match, error)

Returns all upcoming matches for the given game starting from the given time up until the given time.

Careful: the given times are always set to UTC (Zulu) so timezones are not take into account.

func (*Client) GetAllUpcomingMatchesForSeries

func (c *Client) GetAllUpcomingMatchesForSeries(game Game, seriesID int) ([]Match, error)

Returns all upcoming matches for the given game & series ID.

func (*Client) Request

func (c *Client) Request(game Game, path string) *Request

Construct a new request for the given game with the given path.

type Game

type Game string

Game represents a single game in the PandaScore API (eg. csgo, dota2, ...)

const (
	CSGO  Game = "csgo"
	Dota2 Game = "dota2"
	LoL   Game = "lol"
)

func (Game) IsValid

func (g Game) IsValid() bool

Validates that the access token is valid.

type League

type League struct {
	ID       int       `json:"id"`
	Name     string    `json:"name"`
	Modified time.Time `json:"modified_at"`
	URL      string    `json:"url"`
}

League represents a logical group of series, which are events that belong to a league.

More information: https://developers.pandascore.co/doc/#section/Introduction/Events-hierarchy

type Match

type Match struct {
	ID        int             `json:"id"`
	Name      string          `json:"name"`
	BeginsAt  time.Time       `json:"begin_at"`
	Modified  time.Time       `json:"modified_at"`
	LiveURL   string          `json:"live_url"`
	Videogame Videogame       `json:"videogame"`
	Opponents []MatchOpponent `json:"opponents"`
	Series    Series          `json:"serie"`
	League    League          `json:"league"`
}

Match represents an instance of a single match between 2 opponents (teams or players).

More information: https://developers.pandascore.co/doc/#section/Introduction/Events-hierarchy

type MatchOpponent

type MatchOpponent struct {
	Type     string   `json:"type"`
	Opponent Opponent `json:"opponent"`
}

MatchOpponent represents an opponent as defined for a specific match. Whether the opponent is a team is defined on this level, which I find really weird.

type Opponent

type Opponent struct {
	Name     string `json:"name"`
	Location string `json:"location"`
	LogoURL  string `json:"image_url"`
}

Opponent represents a single opponent that partakes in a match.

type PandaScoreError

type PandaScoreError struct {
	Message string `json:"error"`
}

Represents an error coming directly from the PandaScore API (eg. no or invalid access token).

func (*PandaScoreError) Error

func (pse *PandaScoreError) Error() string

type Request

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

PandaScore API request with it's attributes

func (*Request) Filter

func (r *Request) Filter(field string, value ...string) *Request

Adds a filter parameter to the request, where the given field must match the given value.

More information: https://developers.pandascore.co/doc/index.htm#section/Introduction/Filtering

func (*Request) Get

func (r *Request) Get(value interface{}) (Response, error)

Execute a single request against the PandaScore API to fetch the first page of results and marshal the response body in the struct pointed to by value. Typically value will be an array of some struct, eg. []Series

In case there was an error executing the request, an empty response struct is returned.

func (*Request) GetAll

func (r *Request) GetAll(value interface{}) (Response, error)

Execute multiple requests against the PandaScore API to fetch all results from all pages and marshal the response body in the struct pointed to by value. Typically value will be an array of some struct, eg. []League

In case there was an error executing the request, an empty response struct is returned.

func (*Request) Page

func (r *Request) Page(page int) *Request

Adds the given page number to the request. Input cannot be <= 0, if it is then the page is set to 1.

More information: https://developers.pandascore.co/doc/index_dota2.htm#section/Introduction/Pagination

func (*Request) PageSize

func (r *Request) PageSize(size int) *Request

Set the given page size for the request. Page size must be larger than 0 and less than, or equal to, 100. The default page size is 50 if the given size is invalid.

func (*Request) Range

func (r *Request) Range(field string, lowerBound string, upperBound string) *Request

Adds a range parameter to the request, typically dates, where the given field must have a value between the given bounds.

More information: https://developers.pandascore.co/doc/#section/Introduction/Range

func (*Request) Search

func (r *Request) Search(field string, value string) *Request

Adds a search parameter to the request, where the given field must contain the given value.

More information: https://developers.pandascore.co/doc/index.htm#section/Introduction/Search

func (*Request) Sort

func (r *Request) Sort(field string, order Sorting) *Request

Adds a sort parameter to the request.

More information: https://developers.pandascore.co/doc/index.htm#section/Introduction/Sorting

type Response

type Response struct {
	CurrentPage    int
	ResultsPerPage int
	TotalResults   int
}

Response as parsed from a PandaScore API. Important: this is not the actual response body but rather any other information (headers, etc.) that might be useful for a caller to get.

func (*Response) HasMore

func (r *Response) HasMore() bool

Returns true if there are more pages with more results.

type Series

type Series struct {
	ID       int       `json:"id"`
	FullName string    `json:"full_name"`
	Modified time.Time `json:"modified_at"`
}

Series represents an instance of a league event.

More information: https://developers.pandascore.co/doc/#section/Introduction/Events-hierarchy

type Sorting

type Sorting byte

Sorting used for specifying sorting parameters.

const (
	Ascending  Sorting = 0
	Descending Sorting = 1
)

type Videogame

type Videogame struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

Videogame represents the type of game that this match is being played in.