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.exceptions` - Exceptions¶

`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

Table Of Contents

Previous topic

This Page

Modules¶

`boardgamegeek.api` - Core functions¶

`boardgamegeek.collection` - Collection information¶

`boardgamegeek.exceptions` - Exceptions¶

`boardgamegeek.games` - Games information¶

`boardgamegeek.guild` - Guild information¶

`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¶

Modules¶

boardgamegeek.api - Core functions¶

boardgamegeek.collection - Collection information¶

boardgamegeek.exceptions - Exceptions¶

boardgamegeek.games - Games information¶

boardgamegeek.guild - Guild information¶

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¶

`boardgamegeek.api` - Core functions¶

`boardgamegeek.collection` - Collection information¶

`boardgamegeek.exceptions` - Exceptions¶

`boardgamegeek.games` - Games information¶

`boardgamegeek.guild` - Guild information¶

`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¶