Modules

boardgamegeek.api - Core functions

This module contains the core functionality needed to retrieve data from boardgamegeek.com and parse it into usable objects.

class boardgamegeek.api.BoardGameGeek(cache=u'memory:///?ttl=3600', timeout=15, retries=3, retry_delay=5, disable_ssl=False, requests_per_minute=30)[source]

Python interface for www.boardgamegeek.com’s XML API 2.

Caching for the requests can be used by specifying an URI for the cache parameter. By default, an in-memory cache is used, with sqlite being the other currently supported option.

Parameters:
  • cache – URL indicating the cache to use for HTTP requests, None if disabled
  • timeout – Timeout for network operations
  • retries – Number of retries to perform in case the API returns HTTP 202 (retry) or in case of timeouts
  • retry_delay – Time to sleep between retries when the API returns HTTP 202 (retry)
  • disable_ssl – If true, use HTTP instead of HTTPS for calling the BGG API
  • requests_per_minute – how many requests per minute to allow to go out to BGG (throttle prevention)

Example usage:

>>> bgg = BoardGameGeek()
>>> game = bgg.game("Android: Netrunner")
>>> game.id
124742
>>> bgg_no_cache = BoardGameGeek(cache=None)
>>> bgg_sqlite_cache = BoardGameGeek(cache="sqlite:///path/to/cache.db?ttl=3600")
collection(user_name)

Returns the user’s game collection

Parameters:user_name (str) – user name to retrieve the collection for
Returns:Collection object
Return type:boardgamegeek.collection.Collection
Returns:None if user not found
Raises:boardgamegeek.exceptions.BoardGameGeekError in case of invalid parameters
Raises:boardgamegeek.exceptions.BoardGameGeekAPIRetryError if this request should be retried after a short delay
Raises:boardgamegeek.exceptions.BoardGameGeekAPIError if the response couldn’t be parsed
Raises:boardgamegeek.exceptions.BoardGameGeekTimeoutError if there was a timeout
game(name=None, game_id=None, choose=u'first')[source]

Get information about a game.

Parameters:
  • name (str) – If not None, get information about a game with this name
  • game_id (integer) – If not None, get information about a game with this id
  • choose (str) – method of selecting the game by name, when dealing with multiple results. Valid values are “first”, “recent” or “best-rank”
Returns:

BoardGame object

Return type:

boardgamegeek.games.BoardGame

Returns:

None if the game wasn’t found

Raises:

boardgamegeek.exceptions.BoardGameGeekError in case of invalid name or game_id

Raises:

boardgamegeek.exceptions.BoardGameGeekAPIRetryError if this request should be retried after a short delay

Raises:

boardgamegeek.exceptions.BoardGameGeekAPIError if the response couldn’t be parsed

Raises:

boardgamegeek.exceptions.BoardGameGeekTimeoutError if there was a timeout

games(name)[source]

Return a list containing all games with the given name

Parameters:name (str) – the name of the game to search for
Returns:list of boardgamegeek.games.BoardGame
Raises:boardgamegeek.exceptions.BoardGameGeekAPIRetryError if this request should be retried after a short delay
Raises:boardgamegeek.exceptions.BoardGameGeekAPIError if the response couldn’t be parsed
Raises:boardgamegeek.exceptions.BoardGameGeekTimeoutError if there was a timeout
get_game_id(name, choose=u'first')[source]

Returns the BGG ID of a game, searching by name

Parameters:
  • name (str) – The name of the game to search for
  • choose (str) – method of selecting the game by name, when dealing with multiple results. Valid values are “first”, “recent” or “best-rank”
Returns:

the game’s id

Return type:

integer

Returns:

None if game wasn’t found

Raises:

boardgamegeek.exceptions.BoardGameGeekError in case of invalid name

Raises:

boardgamegeek.exceptions.BoardGameGeekAPIRetryError if this request should be retried after a short delay

Raises:

boardgamegeek.exceptions.BoardGameGeekAPIError if the response couldn’t be parsed

Raises:

boardgamegeek.exceptions.BoardGameGeekTimeoutError if there was a timeout

guild(guild_id, progress=None)

Retrieves details about a guild

Parameters:
  • guild_id (integer) – the id number of the guild
  • progress (callable) – an optional callable for reporting progress, taking two integers (current, total) as arguments
Returns:

Guild object containing the data

Returns:

None if the information couldn’t be retrieved

Return type:

boardgamegeek.guild.Guild

Raises:

boardgamegeek.exceptions.BoardGameGeekError in case of an invalid guild id

Raises:

boardgamegeek.exceptions.BoardGameGeekAPIRetryError if this request should be retried after a short delay

Raises:

boardgamegeek.exceptions.BoardGameGeekAPIError if the response couldn’t be parsed

Raises:

boardgamegeek.exceptions.BoardGameGeekTimeoutError if there was a timeout

hot_items(item_type)

Return the list of “Hot Items”

Parameters:item_type (str) – hot item type. Valid values: “boardgame”, “rpg”, “videogame”, “boardgameperson”, “rpgperson”, “boardgamecompany”, “rpgcompany”, “videogamecompany”)
Returns:HotItems object
Return type:boardgamegeek.hotitems.HotItems
Returns:None in case the hot items couldn’t be retrieved
Raises:boardgamegeek.exceptions.BoardGameGeekError if the parameter is invalid
Raises:boardgamegeek.exceptions.BoardGameGeekAPIRetryError if this request should be retried after a short delay
Raises:boardgamegeek.exceptions.BoardGameGeekAPIError if the response couldn’t be parsed
Raises:boardgamegeek.exceptions.BoardGameGeekTimeoutError if there was a timeout
plays(name=None, game_id=None, progress=None, min_date=None, max_date=None)

Retrieves the plays for an user (if using name) or for a game (if using game_id)

Parameters:
  • name (str) – user name to retrieve the plays for
  • game_id (integer) – game id to retrieve the plays for
  • progress (callable) – an optional callable for reporting progress, taking two integers (current, total) as arguments
  • min_date (datetime.date) – return only plays of the specified date or later.
  • max_date (datetime.date) – return only plays of the specified date or earlier.
Returns:

object containing all the plays

Return type:

boardgamegeek.plays.Plays

Returns:

None if the user/game couldn’t be found

Raises:

boardgamegeek.exceptions.BoardGameGeekError on errors

Raises:

boardgamegeek.exceptions.BoardGameGeekAPIRetryError if this request should be retried after a short delay

Raises:

boardgamegeek.exceptions.BoardGameGeekAPIError if the response couldn’t be parsed

Raises:

boardgamegeek.exceptions.BoardGameGeekTimeoutError if there was a timeout

search(query, search_type=None, exact=False)

Search for a game

Parameters:
  • query (str) – the string to search for
  • search_type (str) – list of strings indicating what to search for. Valid contained values are: “rpgitem”, “videogame”, “boardgame” (default), “boardgameexpansion”
  • exact (bool) – if True, try to match the name exactly
Returns:

list of SearchResult

Return type:

list of boardgamegeek.search.SearchResult

Raises:

boardgamegeek.exceptions.BoardGameGeekError in case of invalid query

Raises:

boardgamegeek.exceptions.BoardGameGeekAPIRetryError if this request should be retried after a short delay

Raises:

boardgamegeek.exceptions.BoardGameGeekAPIError if the response couldn’t be parsed

Raises:

boardgamegeek.exceptions.BoardGameGeekTimeoutError if there was a timeout

user(name, progress=None)

Retrieves details about an user

Parameters:
  • name (str) – user’s login name
  • progress (callable) – an optional callable for reporting progress when fetching the buddy list/guilds, taking two integers (current, total) as arguments
Returns:

User object

Return type:

boardgamegeek.user.User

Returns:

None if the user couldn’t be found

Raises:

boardgamegeek.exceptions.BoardGameGeekError in case of invalid user name

Raises:

boardgamegeek.exceptions.BoardGameGeekAPIRetryError if this request should be retried after a short delay

Raises:

boardgamegeek.exceptions.BoardGameGeekAPIError if the response couldn’t be parsed

Raises:

boardgamegeek.exceptions.BoardGameGeekTimeoutError if there was a timeout

boardgamegeek.collection - Collection information

class boardgamegeek.collection.Collection(data)[source]

A dictionary-like object represeting a Collection

Parameters:data (dict) – a dictionary containing the collection data
Raises:boardgamegeek.exceptions.BoardGameGeekError in case of invalid data
add_game(game)[source]

Add a game to the Collection

Parameters:game (dict) – game data
Raises:boardgamegeek.exceptions.BoardGameGeekError in case of invalid data
items

Returns the items in the collection

Returns:the items in the collection
Return type:list of boardgamegeek.games.CollectionBoardGame
owner

Return the collection’s owner

Returns:the collection’s owner
Return type:str

boardgamegeek.games - Games information

class boardgamegeek.games.CollectionBoardGame(data)[source]

A boardgame retrieved from the collection information, which has less information than the one retrieved via the /thing api and which also contains some user-specific information.

for_trade
Returns:game for trading
Return type:bool
last_modified
Returns:last modified date
Return type:str
owned
Returns:game owned
Return type:bool
preordered
Returns:game preordered
Return type:bool
prev_owned
Returns:game previously owned
Return type:bool
rating
Returns:game rating
Return type:float
Returns:None if n/a
want
Returns:game wanted
Return type:bool
want_to_buy
Returns:want to buy
Return type:bool
want_to_play
Returns:want to play
Return type:bool
wishlist
Returns:game on wishlist
Return type:bool
class boardgamegeek.games.BoardGame(data)[source]

Object containing information about a boardgame

add_expanded_game(data)[source]

Add a game expanded by this one

Parameters:data (dict) – expanded game’s data
Raises:boardgamegeek.exceptions.BoardGameGeekError if data is invalid
add_expansion(data)[source]

Add an expansion of this game

Parameters:data (dict) – expansion data
Raises:boardgamegeek.exceptions.BoardGameGeekError if data is invalid
alternative_names
Returns:alternative names
Return type:list of str
artists
Returns:artists
Return type:list of str
categories
Returns:categories
Return type:list of str
description
Returns:description
Return type:str
designers
Returns:designers
Return type:list of str
expands
Returns:games this item expands
Return type:list of boardgamegeek.things.Thing
expansion
Returns:True if this item is an expansion
Return type:bool
expansions
Returns:expansions
Return type:list of boardgamegeek.things.Thing
families
Returns:families
Return type:list of str
image
Returns:image URL
Return type:str
Returns:None if n/a
implementations
Returns:implementations
Return type:list of str
max_players
Returns:maximum number of players
Return type:integer
Returns:None if n/a
mechanics
Returns:mechanics
Return type:list of str
min_age
Returns:minimum recommended age
Return type:integer
Returns:None if n/a
min_players
Returns:minimum number of players
Return type:integer
Returns:None if n/a
playing_time
Returns:playing time
Return type:integer
Returns:None if n/a
publishers
Returns:publishers
Return type:list of str
ranks
Returns:rankings of this game
Return type:list of dicts, keys: friendlyname (the friendly name of the rank, e.g. “Board Game Rank”), name (name of the rank, e.g “boardgame”), value (the rank)
Returns:None if n/a
rating_average
Returns:average rating
Return type:float
Returns:None if n/a
rating_average_weight
Returns:average weight
Return type:float
Returns:None if n/a
rating_bayes_average
Returns:bayes average rating
Return type:float
Returns:None if n/a
rating_median
Returns:
Return type:float
Returns:None if n/a
rating_num_weights
Returns:
Return type:integer
Returns:None if n/a
rating_stddev
Returns:standard deviation
Return type:float
Returns:None if n/a
thumbnail
Returns:thumbnail URL
Return type:str
Returns:None if n/a
users_commented
Returns:number of user comments
Return type:integer
Returns:None if n/a
users_owned
Returns:number of users owning this game
Return type:integer
Returns:None if n/a
users_rated
Returns:how many users rated the game
Return type:integer
Returns:None if n/a
users_trading
Returns:number of users trading this game
Return type:integer
Returns:None if n/a
users_wanting
Returns:number of users wanting this game
Return type:integer
Returns:None if n/a
users_wishing
Returns:number of users wishing for this game
Return type:integer
Returns:None if n/a
year
Returns:publishing year
Return type:integer
Returns:None if n/a

boardgamegeek.guild - Guild information

class boardgamegeek.guild.Guild(data)[source]

Class containing guild information

addr1
Returns:first field of the address
Return type:str
Returns:None if n/a
addr2
Returns:second field of the address
Return type:str
Returns:None if n/a
address
Returns:address (both fields concatenated)
Return type:str
Returns:None if n/a
category
Returns:category
Return type:str
Returns:None if n/a
city
Returns:city
Return type:str
Returns:None if n/a
country
Returns:country
Return type:str
Returns:None if n/a
description
Returns:description
Return type:str
Returns:None if n/a
manager
Returns:manager
Return type:str
Returns:None if n/a
members
Returns:members of the guild
Return type:list of str
Returns:None if n/a
postalcode
Returns:postal code
Return type:integer
Returns:None if n/a
state
Returns:state or provine
Return type:str
Returns:None if n/a
website
Returns:website address
Return type:str
Returns:None if n/a

boardgamegeek.hotitems - BoardGameGeek “Hot Items”

boardgamegeek.plays - BoardGameGeek “Plays”

boardgamegeek.search - Search results

boardgamegeek.things - Generic objects

boardgamegeek.user - BoardGameGeek “Users”

boardgamegeek.utils - Generic helper functions