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.BGGClient(cache=<boardgamegeek.cache.CacheBackendMemory object>, timeout=15, retries=3, retry_delay=5, disable_ssl=False, requests_per_minute=30)[source]

Python client 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.

:param boardgamegeek.cache.CacheBackend cache: An object to be used for caching the requests :param float timeout: Timeout for network operations, in seconds :param int retries: Number of retries to perform in case the API returns HTTP 202 (retry) or in case of timeouts :param float retry_delay: Time to sleep, in seconds, between retries when the API returns HTTP 202 (retry) :param disable_ssl: ignored, left for backwards compatibility :param requests_per_minute: how many requests per minute to allow to go out to BGG (throttle prevention)

Example usage:

>>> bgg = BGGClient()
>>> game = bgg.game("Android: Netrunner")
>>> game.id
124742
>>> bgg_no_cache = BGGClient(cache=CacheBackendNone())
>>> bgg_sqlite_cache = BGGClient(cache=CacheBackendSqlite(path="/path/to/cache.db", ttl=3600))
collection(user_name, subtype=u'boardgame', exclude_subtype=None, ids=None, versions=False, own=None, rated=None, played=None, commented=None, trade=None, want=None, wishlist=None, wishlist_prio=None, preordered=None, want_to_play=None, want_to_buy=None, prev_owned=None, has_parts=None, want_parts=None, min_rating=None, rating=None, min_bgg_rating=None, bgg_rating=None, min_plays=None, max_plays=None, collection_id=None, modified_since=None)

Returns an user’s game collection

Parameters:
  • user_name (str) – user name to retrieve the collection for
  • subtype (str) – what type of items to return. One of the constants in boardgamegeek.api.BGGRestrictCollectionTo
  • exclude_subtype (str) – if not None (default), exclude the specified subtype. Else, one of the constants in boardgamegeek.api.BGGRestrictCollectionTo
  • ids (list) – if not None (default), limit the results to the specified ids.
  • versions (bool) – include item version information
  • own (bool) – include (if True) or exclude (if False) owned items
  • rated (bool) – include (if True) or exclude (if False) rated items
  • played (bool) – include (if True) or exclude (if False) played items
  • commented (bool) – include (if True) or exclude (if False) items commented on
  • trade (bool) – include (if True) or exclude (if False) items for trade
  • want (bool) – include (if True) or exclude (if False) items wanted in trade
  • wishlist (bool) – include (if True) or exclude (if False) items in the wishlist
  • wishlist_prio (int) – return only the items with the specified wishlist priority (valid values: 1 to 5)
  • preordered (bool) – include (if True) or exclude (if False) preordered items
  • want_to_play (bool) – include (if True) or exclude (if False) items wanting to play
  • want_to_buy (bool) – include (if True) or exclude (if False) items wanting to buy
  • prev_owned (bool) – include (if True) or exclude (if False) previously owned items
  • has_parts (bool) – include (if True) or exclude (if False) items for which there is a comment in the “Has parts” field
  • want_parts (bool) – include (if True) or exclude (if False) items for which there is a comment in the “Want parts” field
  • min_rating (double) – return items rated by the user with a minimum of min_rating
  • rating (double) – return items rated by the user with a maximum of rating

:param double min_bgg_rating : return items rated on BGG with a minimum of min_bgg_rating :param double bgg_rating: return items rated on BGG with a maximum of bgg_rating :param int collection_id: restrict results to the collection specified by this id :param str modified_since: restrict results to those whose status (own, want, etc.) has been changed/added since modified_since. Format: YY-MM-DD or YY-MM-DD HH:MM:SS

Returns:Collection object
Return type:boardgamegeek.collection.Collection
Returns:None if user not found
Raises:boardgamegeek.exceptions.BGGValueError in case of invalid parameter(s)
Raises:boardgamegeek.exceptions.BGGApiRetryError if this request should be retried after a short delay
Raises:boardgamegeek.exceptions.BGGApiError if the response couldn’t be parsed
Raises:boardgamegeek.exceptions.BGGApiTimeoutError if there was a timeout
game(name=None, game_id=None, choose=u'first', versions=False, videos=False, historical=False, marketplace=False, comments=False, rating_comments=False, progress=None)[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”
  • versions (bool) – include versions information
  • videos (bool) – include videos
  • historical (bool) – include historical data
  • marketplace (bool) – include marketplace data
  • comments (bool) – include comments
  • rating_comments (bool) – include comments with rating (ignored in favor of comments, if that is true)
  • progress (callable) – callable for reporting progress if fetching comments
Returns:

BoardGame object

Return type:

boardgamegeek.games.BoardGame

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

game_list(game_id_list=[], versions=False, videos=False, historical=False, marketplace=False)[source]

Get list of games by from a list of ids.

Parameters:
  • game_id_list (list) – List of game ids
  • versions (bool) – include versions information
  • videos (bool) – include videos
  • historical (bool) – include historical data
  • marketplace (bool) – include marketplace data
Returns:

list of BoardGame objects

Return type:

list`

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 (boardgamegeek.BGGChoose) – method of selecting the game by name, when dealing with multiple results.
Returns:

the game’s id

Return type:

integer

Returns:

None if game wasn’t found

Raises:

boardgamegeek.exceptions.BGGError in case of invalid name

Raises:

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

Raises:

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

Raises:

boardgamegeek.exceptions.BGGApiTimeoutError if there was a timeout

guild(guild_id, progress=None, members=True)

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
  • members (bool) – if True, names of the guild members will be fetched
Returns:

Guild object containing the data

Returns:

None if the information couldn’t be retrieved

Return type:

boardgamegeek.guild.Guild

Raises:

BGGValueError in case of an invalid parameter(s)

Raises:

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

Raises:

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

Raises:

boardgamegeek.exceptions.BGGApiTimeoutError 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.BGGValueError in case of invalid parameter(s)
Raises:boardgamegeek.exceptions.BGGApiRetryError if this request should be retried after a short delay
Raises:boardgamegeek.exceptions.BGGApiError if the response couldn’t be parsed
Raises:boardgamegeek.exceptions.BGGApiTimeoutError if there was a timeout
plays(name=None, game_id=None, progress=None, min_date=None, max_date=None, subtype=u'boardgame')

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
  • subtype (str) – limit plays results to the specified subtype.
Returns:

object containing all the plays

Return type:

boardgamegeek.plays.Plays

Returns:

None if the user/game couldn’t be found

Raises:

boardgamegeek.exceptions.BGGValueError in case of invalid parameter(s)

Raises:

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

Raises:

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

Raises:

boardgamegeek.exceptions.BGGApiTimeoutError 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 (list) – list of boardgamegeek.api.BGGRestrictItemTypeTo, indicating what to include in the search results.
  • exact (bool) – if True, try to match the name exactly
Returns:

list of SearchResult

Return type:

list of boardgamegeek.search.SearchResult

Raises:

boardgamegeek.exceptions.BGGValueError in case of invalid parameter(s)

Raises:

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

Raises:

boardgamegeek.exceptions.BGGApiError if the API response was invalid or couldn’t be parsed

Raises:

boardgamegeek.exceptions.BGGApiTimeoutError if there was a timeout

user(name, progress=None, buddies=True, guilds=True, hot=True, top=True, domain=u'boardgame')

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
  • buddies (bool) – if True, get the user’s buddies
  • guilds (bool) – if True, get the user’s guilds
  • hot (bool) – if True, get the user’s “hot” list
  • top (bool) – if True, get the user’s “top” list
  • domain (str) – restrict items on the “hot” and “top” lists to domain. One of the constants in boardgamegeek.BGGSelectDomain
Returns:

User object

Return type:

boardgamegeek.user.User

Returns:

None if the user couldn’t be found

Raises:

ValueError in case of invalid parameters

Raises:

boardgamegeek.exceptions.BGGValueError in case of invalid parameter(s)

Raises:

boardgamegeek.exceptions.BGGItemNotFoundError if the user wasn’t found

Raises:

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

Raises:

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

Raises:

boardgamegeek.exceptions.BGGApiTimeoutError if there was a timeout

boardgamegeek.collection - Collection information

class boardgamegeek.objects.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.objects.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.

comment
Returns:comment left by user
Return type:str
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:user’s rating of the game
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.objects.games.BoardGame(data)[source]

Object containing information about a board game

accessory
Returns:True if this item is an accessory
Return type:bool
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
implementations
Returns:implementations
Return type:list of str
mechanics
Returns:mechanics
Return type:list of str
min_age
Returns:minimum recommended age
Return type:integer
Returns:None if n/a
player_suggestions

:return player suggestion list with votes :rtype: list of dicts

publishers
Returns:publishers
Return type:list of str
rating_average_weight
Returns:average weight
Return type:float
Returns:None if n/a
rating_num_weights
Returns:
Return type:integer
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_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
versions
Returns:versions of this game
Return type:list of boardgamegeek.game.BoardGameVersion
videos
Returns:videos of this game
Return type:list of boardgamegeek.game.BoardGameVideo

boardgamegeek.guild - Guild information

class boardgamegeek.objects.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:set of str
members_count
Returns:number of members, as reported by the server
Return type:int
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