gobgg

package module
v0.9.1 Latest Latest
Warning

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

 Go to latest Published: Feb 15, 2024 License: MIT Imports: 16 Imported by: 3

README

Boardgamegeek API Client for Golang

Go Report Card codecov Go Reference

Basics

Create a new client using the NewBGGClient also you can use the Login function to set the cookies, some API (like posting plays) needs the login cookies.

You can set the http.Client, or http.Cookie or using different domain (do you need to?)

bgg := gobgg.NewBGGClient(gobgg.SetClient(client))
// Setting the cookies (not a requirement if you want to only use public API)
if err := bgg.Login("user", "password"); err != nil {
	log.Fatalf("Login failed with error: %q", err)	
}

Collection API

Getting the collection in boardgamegeek is a little tricky, so the library will retry with a backoff to get the collection. You can control the timeout using the context passed to the function or it will retry forever.

collection, err := bgg.GetCollection(ctx, "fzerorubigd", gobgg.SetCollectionTypes(gobgg.CollectionTypeOwn))

Things API

You can get the things detail (I just use the board game related API so far) it always comes with the statistics (why it should be a flag!)

I decided to follow the same pattern for all the functions even when it is not required.

things , err := bgg.GetThings(ctx, gobgg.GetThingIDs(1, 2, 3))

Plays API

Getting a play is like this:

// For users
plays, err := bgg.Plays(ctx, gobgg.SetUserName("fzerorubigd"))
// For a game
plays, err := bgg.Plays(ctx, gobgg.SetGameID(1))

Posting Plays

Posting play is an experimental API that is not using any documented API end point, for this you need to call Login first.

Person API

For getting the person image you can use the -undocumented- person API PersonImage

Rate Limiting

Boardgamegeek does rate limit on all the api calls. Its a good idea to add a rate limiter to your client. it is already supported and I recommend the

import (
	"fmt"
	"time"

	"go.uber.org/ratelimit"
	"github.com/fzerorubigd/gobgg"
)

rl := ratelimit.New(10, Per(60*time.Second)) // creates a 10 per minutes rate limiter.
client := gobgg.NewBGGClient(gobgg.SetLimiter(rl))

Documentation

Index

Constants

View Source 
const (
	// WishListPriorityMustHave BGA definition
	WishListPriorityMustHave = iota + 1
	// WishListPriorityLoveToHave BGA definition
	WishListPriorityLoveToHave
	// WishListPriorityLikeToHave BGA definition
	WishListPriorityLikeToHave
	// WishListPriorityThinkingAboutIt BGA definition
	WishListPriorityThinkingAboutIt
	// WishListPriorityDoNotBuy BGA definition
	WishListPriorityDoNotBuy
)
View Source 
const (
	// BoardGameCategory is the category link
	BoardGameCategory = "boardgamecategory"
	// BoardGameMechanic is the mechanics link
	BoardGameMechanic = "boardgamemechanic"
	// BoardGameFamily is the family link
	BoardGameFamily = "boardgamefamily"
	// BoardGameDesigner is the designer link
	BoardGameDesigner = "boardgamedesigner"
	// BoardGameArtist is the artist link
	BoardGameArtist = "boardgameartist"
	// BoardGamePublisher is the publisher
	BoardGamePublisher = "boardgamepublisher"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type BGG 

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

BGG is the client for the boardgame geek site

func NewBGGClient 

func NewBGGClient(opt ...OptionSetter) *BGG

NewBGGClient returns a new client

func (*BGG) GetActiveCookies 

func (bgg *BGG) GetActiveCookies() []*http.Cookie

GetActiveCookies return the cookies if the cookies are available

func (*BGG) GetActiveUsername 

func (bgg *BGG) GetActiveUsername() string

GetActiveUsername return the username that the current cookie are based on

func (*BGG) GetCollection 

func (bgg *BGG) GetCollection(ctx context.Context, username string, options ...CollectionOptionSetter) ([]CollectionItem, error)

GetCollection is to get the collections of a user

func (*BGG) GetRankBreakDown 

func (bgg *BGG) GetRankBreakDown(ctx context.Context, gameID int64) (RankBreakDown, error)

func (*BGG) GetThings 

func (bgg *BGG) GetThings(ctx context.Context, setters ...GetOptionSetter) ([]ThingResult, error)

GetThings is the get things API entry point

func (*BGG) GetUser 

func (bgg *BGG) GetUser(ctx context.Context, username string) (*User, error)

GetUser return the user from BGG if exists

func (*BGG) Hotness 

func (bgg *BGG) Hotness(ctx context.Context, count int) ([]IDDelta, error)

func (*BGG) Login 

func (bgg *BGG) Login(ctx context.Context, username, password string) error

Login tries to login into the bgg using the credentials and returns the cookies required for next calls

func (*BGG) PersonImage 

func (bgg *BGG) PersonImage(ctx context.Context, id int64) (*PersonImage, error)

func (*BGG) Plays 

func (bgg *BGG) Plays(ctx context.Context, setter ...PlaysOptionSetter) (*Plays, error)

Plays using plays api of the bgg, it get the list of requested items

func (*BGG) PostPlay 

func (bgg *BGG) PostPlay(ctx context.Context, play *Play) (int, error)

PostPlay save a play record, you should be logged in, and it returns the number of plays after you save this one

func (*BGG) Search 

func (bgg *BGG) Search(ctx context.Context, query string, setter ...SearchOptionSetter) ([]SearchResult, error)

Search using search api of the bgg, it get the list of requested items

func (*BGG) SetRank 

func (bgg *BGG) SetRank(ctx context.Context, objectID int64, rate float64) error

SetRank tries to add rank for an item (experimental)

func (*BGG) TopPages 

func (bgg *BGG) TopPages(ctx context.Context, page int) ([]int64, error)

type CollectionItem 

type CollectionItem struct {
	ID            int64    `json:"id,omitempty"`
	CollID        int64    `json:"coll_id"`
	Name          string   `json:"name,omitempty"`
	Description   string   `json:"description,omitempty"`
	Type          ItemType `json:"type,omitempty"`
	YearPublished int      `json:"year_published,omitempty"`
	Thumbnail     string   `json:"thumbnail,omitempty"`
	Image         string   `json:"image,omitempty"`

	CollectionStatus []string `json:"collection_status,omitempty"`
}

CollectionItem is the item in collection

type CollectionOptionSetter 

type CollectionOptionSetter func(*GetCollectionOptions)

CollectionOptionSetter is the option setter for the get collection

func SetBGGRating 

func SetBGGRating(rate int) CollectionOptionSetter

SetBGGRating is the exact bgg rating for this item

func SetCollID 

func SetCollID(collID int64) CollectionOptionSetter

func SetCollectionTypes 

func SetCollectionTypes(typ ...CollectionType) CollectionOptionSetter

SetCollectionTypes returns the collection types

func SetExcludeSubtype 

func SetExcludeSubtype(subType ItemType) CollectionOptionSetter

SetExcludeSubtype Specifies which subtype you want to exclude from the results.

func SetIDs 

func SetIDs(ids ...int64) CollectionOptionSetter

func SetMaxPlays 

func SetMaxPlays(plays int) CollectionOptionSetter

SetMaxPlays show games with max plays

func SetMinBGGRating 

func SetMinBGGRating(rate int) CollectionOptionSetter

SetMinBGGRating is the minimum bgg rating for this item

func SetMinPlays 

func SetMinPlays(plays int) CollectionOptionSetter

SetMinPlays show games with min plays

func SetMinRating 

func SetMinRating(rate int) CollectionOptionSetter

SetMinRating is the minimum personal rating for this item for this user

func SetModifiedSince 

func SetModifiedSince(t time.Time) CollectionOptionSetter

SetModifiedSince to set the modified since flag

func SetRating 

func SetRating(rate int) CollectionOptionSetter

SetRating is the exact personal rating for this item for this user

func SetSubType 

func SetSubType(subType ItemType) CollectionOptionSetter

SetSubType Specifies which collection you want to retrieve. TYPE may be boardgame, boardgameexpansion, boardgameaccessory, rpgitem, rpgissue, or videogame; the default is boardgame

func SetVersion 

func SetVersion(version bool) CollectionOptionSetter

SetVersion Returns version info for each item in your collection.

type CollectionType 

type CollectionType string

CollectionType is the bgg collection type 

const (
	// CollectionTypeOwn is the owned items
	CollectionTypeOwn CollectionType = "own"
	// CollectionTypeRated is rated items
	CollectionTypeRated CollectionType = "rated"
	// CollectionTypePlayed is played items
	CollectionTypePlayed CollectionType = "played"
	// CollectionTypeComment is commented items
	CollectionTypeComment CollectionType = "comment"
	// CollectionTypeTrade is in trade list item
	CollectionTypeTrade CollectionType = "trade"
	// CollectionTypeWant is in want list item
	CollectionTypeWant CollectionType = "want"
	// CollectionTypeWishList is the wishlist items
	CollectionTypeWishList CollectionType = "wishlist"
	// CollectionTypePreorder is the pre orders item
	CollectionTypePreorder CollectionType = "preorder"
	// CollectionTypeWantToPlay is want to play items
	CollectionTypeWantToPlay CollectionType = "wanttoplay"
	// CollectionTypeWantToBuy is want to buy items
	CollectionTypeWantToBuy CollectionType = "wanttobuy"
	// CollectionTypePrevOwned is previously owned items
	CollectionTypePrevOwned CollectionType = "prevowned"
	// CollectionTypeHasParts has parts item
	CollectionTypeHasParts CollectionType = "hasparts"
	// CollectionTypeWantParts want parts item
	CollectionTypeWantParts CollectionType = "wantparts"
)

type FamilyRank 

type FamilyRank struct {
	ID           int64   `json:"id,omitempty"`
	Name         string  `json:"name,omitempty"`
	FriendlyName string  `json:"friendly_name,omitempty"`
	Rank         int     `json:"rank,omitempty"`
	BayesAverage float64 `json:"bayes_average,omitempty"`
}

type GetCollectionOptions 

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

GetCollectionOptions is the option used to handle the collection request

type GetOptionSetter 

type GetOptionSetter func(*GetThingOption)

GetOptionSetter is the option setter for the GetThing api

func GetThingIDs 

func GetThingIDs(ids ...int64) GetOptionSetter

GetThingIDs is for setting IDs

type GetThingOption 

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

GetThingOption is the options for the GetThing api

type IDDelta 

type IDDelta struct {
	ID    int64
	Delta int
}

type Item 

type Item struct {
	Name string   `json:"name,omitempty"`
	Type ItemType `json:"type,omitempty"`
	ID   int64    `json:"id,omitempty"`
}

type ItemType 

type ItemType string

ItemType is the item type for the search api 

const (
	// RPGItemType for rpg
	RPGItemType ItemType = "rpgitem"
	// VideGameType for video game
	VideGameType ItemType = "videogame"
	// BoardGameType for board game
	BoardGameType ItemType = "boardgame"
	// BoardGameAccessoryType for accessory
	BoardGameAccessoryType ItemType = "boardgameaccessory"
	// BoardGameExpansionType for expansion
	BoardGameExpansionType ItemType = "boardgameexpansion"
)

type Limiter added in v0.7.0 

type Limiter interface {
	// Take should block to make sure that the RPS is met.
	Take() time.Time
}

Limiter is a rate limiter interface from the go.uber.org/ratelimit the package itself is not needed, but can be used with this client 

type Link struct {
	ID   int64  `json:"id,omitempty"`
	Name string `json:"name,omitempty"`
}

Link is the link

type LinkStruct 

type LinkStruct struct {
	Text    string `xml:",chardata"`
	Type    string `xml:"type,attr"`
	ID      int64  `xml:"id,attr"`
	Value   string `xml:"value,attr"`
	Inbound string `xml:"inbound,attr"`
}

LinkStruct is for the link for the things

type NameStruct 

type NameStruct struct {
	Text      string `xml:",chardata"`
	Type      string `xml:"type,attr"`
	Sortindex string `xml:"sortindex,attr"`
	Value     string `xml:"value,attr"`
}

NameStruct is the name from the api

type OptionSetter 

type OptionSetter func(*BGG)

OptionSetter modify the internal settings

func SetClient 

func SetClient(client *http.Client) OptionSetter

SetClient allows you to modify the default client

func SetCookies 

func SetCookies(username string, c []*http.Cookie) OptionSetter

SetCookies set the cookies for this object, in case the user is logged in already

func SetHost 

func SetHost(host string) OptionSetter

SetHost changes the host, default is boardgamegeek.com

func SetLimiter added in v0.7.0 

func SetLimiter(limiter Limiter) OptionSetter

SetLimiter can use tos et a limiter to limit the api call to the BGG

func SetSchema 

func SetSchema(schema string) OptionSetter

SetSchema changes the schema, default is https

type PersonImage 

type PersonImage struct {
	ID        int64  `json:"id,omitempty"`
	Thumbnail string `json:"thumbnail,omitempty"`
	Image     string `json:"image,omitempty"`
}

PersonImage is the persons image and thumbnail

type Play 

type Play struct {
	ID         int64         `json:"id,omitempty"`
	Date       time.Time     `json:"date,omitempty"`
	Quantity   int64         `json:"quantity,omitempty"`
	Length     time.Duration `json:"length,omitempty"`
	Incomplete bool          `json:"incomplete,omitempty"`
	NowInStats bool          `json:"now_in_stats,omitempty"`
	Location   string        `json:"location,omitempty"`
	Comment    string        `json:"comment,omitempty"`
	Item       Item          `json:"item,omitempty"`
	Players    []Player      `json:"players,omitempty"`
}

type Player 

type Player struct {
	UserName      string `json:"user_name,omitempty"`
	UserID        string `json:"user_id,omitempty"`
	Name          string `json:"name,omitempty"`
	StartPosition string `json:"start_position,omitempty"`
	Color         string `json:"color,omitempty"`
	Score         int64  `json:"score,omitempty"`
	New           bool   `json:"new,omitempty"`
	Rating        string `json:"rating,omitempty"`
	Win           bool   `json:"win,omitempty"`
}

type Plays 

type Plays struct {
	Total    int64  `json:"total,omitempty"`
	Page     int64  `json:"page,omitempty"`
	UserName string `json:"user_name,omitempty"`
	UserID   int64  `json:"user_id,omitempty"`
	Items    []Play `json:"items,omitempty"`
}

type PlaysOption 

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

PlaysOption is used to handle func option ins plays api

type PlaysOptionSetter 

type PlaysOptionSetter func(*PlaysOption)

PlaysOptionSetter is used to handle the func option in plays api

func SetDateRangeMax 

func SetDateRangeMax(max time.Time) PlaysOptionSetter

SetDateRangeMax set the min date

func SetDateRangeMin 

func SetDateRangeMin(min time.Time) PlaysOptionSetter

SetDateRangeMin set the min date

func SetGameID 

func SetGameID(id int) PlaysOptionSetter

SetGameID to set the game id

func SetPageNumber 

func SetPageNumber(page int) PlaysOptionSetter

SetPageNumber set the current page

func SetUserName 

func SetUserName(name string) PlaysOptionSetter

SetUserName for the plays

type Poll 

type Poll struct{}

type PollItem 

type PollItem struct {
	Name       string
	Title      string
	TotalVotes int
}

PollItem is a single poll item in a poll

type PollStruct 

type PollStruct struct {
	Text       string `xml:",chardata"`
	Name       string `xml:"name,attr"`
	Title      string `xml:"title,attr"`
	Totalvotes string `xml:"totalvotes,attr"`
	Results    []struct {
		Text       string `xml:",chardata"`
		Numplayers string `xml:"numplayers,attr"`
		Result     []struct {
			Text     string `xml:",chardata"`
			Value    string `xml:"value,attr"`
			Numvotes int    `xml:"numvotes,attr"`
			Level    string `xml:"level,attr"`
		} `xml:"result"`
	} `xml:"results"`
}

PollStruct is the poll

type RankBreakDown 

type RankBreakDown [10]int64

RankBreakDown shows the rank break down in BGG website

func (RankBreakDown) Average 

func (rb RankBreakDown) Average() float64

func (RankBreakDown) BayesianAverage 

func (rb RankBreakDown) BayesianAverage(added int64) float64

func (RankBreakDown) Total 

func (rb RankBreakDown) Total() int64

type SearchOption 

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

SearchOption is used to handle func option ins earch api

type SearchOptionSetter 

type SearchOptionSetter func(*SearchOption)

SearchOptionSetter is used to handle the func option in search api

func SearchExact 

func SearchExact() SearchOptionSetter

SearchExact set the exact argument for bgg

func SearchTypes 

func SearchTypes(types ...ItemType) SearchOptionSetter

SearchTypes set the valid types for the api

type SearchResult 

type SearchResult struct {
	ID             int64
	Name           string
	AlternateNames []string
	Type           ItemType
	YearPublished  int // Zero means no data
}

SearchResult is the result for the search

type SimpleString 

type SimpleString struct {
	Text  string `xml:",chardata"`
	Value string `xml:"value,attr"`
}

SimpleString is the string

func (*SimpleString) String 

func (s *SimpleString) String() string

type Statistics 

type Statistics struct {
	Text    string `xml:",chardata"`
	Page    string `xml:"page,attr"`
	Ratings struct {
		Text       string `xml:",chardata"`
		Usersrated struct {
			Text  string `xml:",chardata"`
			Value string `xml:"value,attr"`
		} `xml:"usersrated"`
		Average struct {
			Text  string `xml:",chardata"`
			Value string `xml:"value,attr"`
		} `xml:"average"`
		Bayesaverage struct {
			Text  string `xml:",chardata"`
			Value string `xml:"value,attr"`
		} `xml:"bayesaverage"`
		Ranks struct {
			Text string `xml:",chardata"`
			Rank []struct {
				Text         string `xml:",chardata"`
				Type         string `xml:"type,attr"`
				ID           string `xml:"id,attr"`
				Name         string `xml:"name,attr"`
				Friendlyname string `xml:"friendlyname,attr"`
				Value        string `xml:"value,attr"`
				Bayesaverage string `xml:"bayesaverage,attr"`
			} `xml:"rank"`
		} `xml:"ranks"`
		Stddev struct {
			Text  string `xml:",chardata"`
			Value string `xml:"value,attr"`
		} `xml:"stddev"`
		Median struct {
			Text  string `xml:",chardata"`
			Value string `xml:"value,attr"`
		} `xml:"median"`
		Owned struct {
			Text  string `xml:",chardata"`
			Value string `xml:"value,attr"`
		} `xml:"owned"`
		Trading struct {
			Text  string `xml:",chardata"`
			Value string `xml:"value,attr"`
		} `xml:"trading"`
		Wanting struct {
			Text  string `xml:",chardata"`
			Value string `xml:"value,attr"`
		} `xml:"wanting"`
		Wishing struct {
			Text  string `xml:",chardata"`
			Value string `xml:"value,attr"`
		} `xml:"wishing"`
		Numcomments struct {
			Text  string `xml:",chardata"`
			Value string `xml:"value,attr"`
		} `xml:"numcomments"`
		Numweights struct {
			Text  string `xml:",chardata"`
			Value string `xml:"value,attr"`
		} `xml:"numweights"`
		Averageweight struct {
			Text  string `xml:",chardata"`
			Value string `xml:"value,attr"`
		} `xml:"averageweight"`
	} `xml:"ratings"`
}

type SuggestedPlayerCount 

type SuggestedPlayerCount struct {
	NumPlayers     string
	Best           int
	Recommended    int
	NotRecommended int
}

SuggestedPlayerCount is a structure that shows the suggested player count based on user voting

func (*SuggestedPlayerCount) BestPercentile 

func (sp *SuggestedPlayerCount) BestPercentile() float32

func (*SuggestedPlayerCount) NotRecommendedPercentile 

func (sp *SuggestedPlayerCount) NotRecommendedPercentile() float32

func (*SuggestedPlayerCount) RecommendedPercentile 

func (sp *SuggestedPlayerCount) RecommendedPercentile() float32

func (*SuggestedPlayerCount) Suggestion 

func (sp *SuggestedPlayerCount) Suggestion() (ThreeRating, int, float32)

type ThingResult 

type ThingResult struct {
	ID             int64    `json:"id,omitempty"`
	Name           string   `json:"name,omitempty"`
	AlternateNames []string `json:"alternate_names,omitempty"`
	Type           ItemType `json:"type,omitempty"`
	YearPublished  int      `json:"year_published,omitempty"`

	Thumbnail string `json:"thumbnail,omitempty"`
	Image     string `json:"image,omitempty"`

	MinPlayers int `json:"min_players,omitempty"`
	MaxPlayers int `json:"max_players,omitempty"`

	SuggestedPlayerCount []SuggestedPlayerCount

	// TODO: int?
	MinAge string `json:"min_age,omitempty"`

	PlayTime    string `json:"play_time,omitempty"`
	MinPlayTime string `json:"min_play_time,omitempty"`
	MaxPlayTime string `json:"max_play_time,omitempty"`

	Description string `json:"description,omitempty"`

	Links map[string][]Link `json:"links,omitempty"`

	UsersRated   int     `json:"users_rated,omitempty"`
	AverageRate  float64 `json:"average_rate,omitempty"`
	BayesAverage float64 `json:"bayes_average,omitempty"`

	UsersOwned    int     `json:"users_owned,omitempty"`
	UsersTrading  int     `json:"users_trading,omitempty"`
	UsersWanting  int     `json:"users_wanting,omitempty"`
	UsersWishing  int     `json:"users_wishing,omitempty"`
	NumComments   int     `json:"num_comments,omitempty"`
	NumWeight     int     `json:"num_weight,omitempty"`
	AverageWeight float64 `json:"average_weight,omitempty"`

	RankTotal int                   `json:"rank_total,omitempty"`
	Family    map[string]FamilyRank `json:"family,omitempty"`
}

ThingResult is the result for the thing api

func (*ThingResult) Artists added in v0.7.2 

func (tr *ThingResult) Artists() []Link

Artists return board game artists

func (*ThingResult) Categories added in v0.7.2 

func (tr *ThingResult) Categories() []Link

Categories return board game categories

func (*ThingResult) Designers added in v0.7.2 

func (tr *ThingResult) Designers() []Link

Designers return board game designers

func (*ThingResult) Families added in v0.7.2 

func (tr *ThingResult) Families() []Link

Families return board game families

func (*ThingResult) GetLinkByName added in v0.7.2 

func (tr *ThingResult) GetLinkByName(name string) []Link

GetLinkByName return the link by its name (if available) and return empty link if not

func (*ThingResult) Mechanics added in v0.7.2 

func (tr *ThingResult) Mechanics() []Link

Mechanics return board game mechanics

func (*ThingResult) Publishers added in v0.7.2 

func (tr *ThingResult) Publishers() []Link

Publishers return board game publishers

type ThreeRating added in v0.7.1 

type ThreeRating int

ThreeRating is a rating type for Best/Recommended/Not Recommended 

const (
	// NotRecommended is not recommended
	NotRecommended ThreeRating = iota
	// Recommended
	Recommended
	// Best
	Best
)

func (ThreeRating) String added in v0.7.1 

func (t ThreeRating) String() string

type User 

type User struct {
	UserID     int64  `json:"user_id"`
	UserName   string `json:"user_name"`
	FirstName  string `json:"first_name,omitempty"`
	LastName   string `json:"last_name,omitempty"`
	Year       int    `json:"year"`
	AvatarLink string `json:"avatar_link,omitempty"`
}

User is a single bgg user

Source Files

View all Source files

Directories

Path Synopsis
cmd
bggcli
collections
plays

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.