BGG XML API redirected from XML API

Introduction

You can access some information from the geek via the BoardGameGeek XML API. Each base URI is described and the various parameters are listed. The parameters and their values are URL-encoded in the standard manner. There are some examples at the end. The resultant output XML is not described here, but XML is "self-describing" right? The output should be quite clear from simple inspection.

For all of the parameters mentioned below, the first parameter you list follows a ? (question mark), and each subsequent parameter follows an & (ampersand).

Commands

Search for games by name and by AKAs

/xmlapi/search

• Parameters:
  • search: String to search for (required)
    • Syntax: /xmlapi/search?search=<searchString>
    • Example: http://www.boardgamegeek.com/xmlapi/search?search=Crossbows%20and%20Catapults
  • exact: Exact name/aka search only (set it to 1, absent by default) [exact doesn't seem to work yet in BGG 2.0]
    • Syntax: /xmlapi/search?search=<searchString>&exact=1
    • Example: http://www.boardgamegeek.com/xmlapi/search?search=Crossbows%20and%20Catapults&exact=1

Retrieve information about a particular game or games

/xmlapi/boardgame/<gameid>
/xmlapi/boardgame/<gameid>,<gameid2>[...]

• Example, single game: http://www.boardgamegeek.com/xmlapi/boardgame/35424
• Example, multiple games: http://www.boardgamegeek.com/xmlapi/boardgame/35424,2860
• Parameters:
  • comments: Show users' comments on games (set it to 1, absent by default)
    • Syntax: /xmlapi/boardgame/<gameId>?comments=1
    • Example: http://www.boardgamegeek.com/xmlapi/boardgame/35424,2860?comments=1
  • stats: Include game statistics (set it to 1, absent by default)
    • Syntax: /xmlapi/boardgame/<gameId>?stats=1
    • Example: http://www.boardgamegeek.com/xmlapi/boardgame/2860?stats=1
  • historical: Include historical game statistics (set it to 1, absent by default) - Use from/end parameters to set starting and ending dates. Returns all data starting from 2006-03-18.
    • Syntax: /xmlapi/boardgame/<gameId>?historical=1
    • Example: http://www.boardgamegeek.com/xmlapi/boardgame/35424,2860?historical=1
    • from: Set the start date to include historical data (format: YYYY-MM-DD, absent by default )
    • to: Set the end date to include historical data (format: YYYY-MM-DD, absent by default )
      • Syntax: /xmlapi/boardgame/<gameId>?historical=1&from=<date>&to=<date>
      • Example: http://www.boardgamegeek.com/xmlapi/boardgame/35424,2860?historical=1&from=2009-01-01&to=2009-03-17

Retrieve games in a user's collection

/xmlapi/collection/<username>
Retrieve games in a user's collection. Important definition: A user's collection includes any games the user has added to her collection on BGG. This includes games she owns, games she used to own, games she's rated, games upon which she's commented, games she's played, and games on her wishlist, just to name a few. In this section, references to the collection mean this broader sense of BGG collection, not the user's personal stash of games.

• Example: http://www.boardgamegeek.com/xmlapi/collection/eekspider
• Filters: (You can use any combination of the below)
  • own: In (or exclude for 0) a user's collection. That is, the user currently owns it. Collections include games that
    • Syntax: /xmlapi/collection/<username>?own=<0,1>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?own=0 - games in zefquaavius' collection that he doesn't own
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?own=1 - games zefquaavius owns
  • rated
    • Syntax: /xmlapi/collection/<username>?rated=<0,1>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?rated=0 - games in zefquaavius' collection that he has not rated
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?rated=1 - games zefquaavius has rated
  • played
    • Syntax: /xmlapi/collection/<username>?played=<0,1>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?played=0 - games in zefquaavius' collection for which he has never logged any plays
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?played=1 - games for which zefquaavius has logged plays
  • comment: include (or exclude) games with comments
    • Syntax: /xmlapi/collection/<username>?comment=<0,1>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?comment=0 - games in zefquaavius' collection upon which he currently has comments
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?comment=1 - games upon which zefquaavius has comments
  • trade: games listed for trade
    • Syntax: /xmlapi/collection/<username>?trade=<0,1>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?trade=0 - games in zefquaavius' collection he is not offering for trade
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?trade=1 - games zefquaavius is offering for trade
  • want
    • Syntax: /xmlapi/collection/<username>?want=<0,1>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?comment=0 - games in zefquaavius' collection for which he is not trying to trade anything (i.e. He's not looking to trade for your copy of it.)
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?comment=1 - games for which zefquaavius is willing to make a trade
  • wishlist
    • Syntax: /xmlapi/collection/<username>?wishlist=<0,1>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?wishlist=0 - games in zefquaavius' collection that are not on his wishlist
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?wishlist=1 - games in zefquaavius' wishlist
  • wanttoplay
    • Syntax: /xmlapi/collection/<username>?wanttoplay=<0,1>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?wanttoplay=0 - games in zefquaavius' collection which he has no pressing desire to play
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?wanttoplay=1 - games zefquaavius currently wants to play
  • wanttobuy
    • Syntax: /xmlapi/collection/<username>?wanttobuy=<0,1>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?wanttobuy=0 - games in zefquaavius' collection he doesn't wish to buy
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?wanttobuy=1 - games zefquaavius wishes to buy
  • prevowned
    • Syntax: /xmlapi/collection/<username>?prevowned=<0,1>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?prevowned=1 - games zefquaavius previously owned
  • preordered
    • Syntax: /xmlapi/collection/<username>?preordered=<0,1>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?preordered=1 - games zefquaavius has pre-ordered
  • hasparts
    • Syntax: /xmlapi/collection/<username>?hasparts=<0,1>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?hasparts=1 - zefquaavius has spare parts of these games up for offer
  • wantparts
    • Syntax: /xmlapi/collection/<username>?wantparts=<0,1>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?wantparts=1 - zefquaavius is looking for spare parts for these games
  • notifycontent
    • Syntax: /xmlapi/collection/<username>?notifycontent=<0,1>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?notifycontent=1 - zefquaavius gets a geekmail whenever these games receive new content on BGG
  • notifysale
    • Syntax: /xmlapi/collection/<username>?notifysale=<0,1>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?notifysale=1 - zefquaavius gets a geekmail whenever a copy of these games are listed in BGGM
  • notifyauction
    • Syntax: /xmlapi/collection/<username>?notifyauction=<0,1>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?notifyauction=1 - zefquaavius gets a geekmail whenever a copy is listed in a geekgold or eBay auction that's listed on BGG
  • wishlistpriority: (a number from 1 to 5)
    • Syntax: /xmlapi/collection/<username>?wishlistpriority=<0,1>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?wishlistpriority=4 - games zefquaavius has given a wishlist priority of 4 ("Thinking about it")
  • minrating: minimum and maximum user rating
    • Syntax: /xmlapi/collection/<username>?minrating=<1-10>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?minrating=9 - games zefquaavius has given a rating of at least 9
  • maxrating
    • Syntax: /xmlapi/collection/<username>?maxrating=<1-10>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?maxrating=2 - games zefquaavius has given a rating of no more than 2 [Note: May be broken in BGG 2.0, or may require other parameters.]
  • minbggrating: minimum and maximum bgg rating
    • Syntax: /xmlapi/collection/<username>?minbggrating=<1-10>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?minbggrating=8 - games in zefquaavius' collection with an average BGG rating of at least 8
  • maxbggrating
    • Syntax: /xmlapi/collection/<username>?maxbggrating=<1-10>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?maxbggrating=2 - games in zefquaavius' collection with an average BGG rating no more than 2 [Note: May be broken in BGG 2.0, or may require other parameters.]
  • minplays: minumum and maximum number of recorded plays
    • Syntax: /xmlapi/collection/<username>?minplays=<number>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?minplays=50 - games zefquaavius has played 50 or more times
  • maxplays
    • Syntax: /xmlapi/collection/<username>?maxplays=<number>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?minplays=50&maxplays=99 - games zefquaavius has played more than 49 times, but fewer than 100 times
• Other parameters:
  • showprivate: Show the private fields (purchase price, etc). Default is 1 for logged in users, 0 otherwise, and showprivate=1 only works on your own collection, when you are logged in.
    • Syntax: /xmlapi/collection/<username>?showprivate=<0,1>
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?showprivate=1 - include private info zefquaavius has listed, provided you're zefquaavius
    • Example: http://www.boardgamegeek.com/xmlapi/collection/zefquaavius?showprivate=0 - If you're zefquaavius, see what everyone else sees when viewing your collection: No private info

Retrieve the messages from a forum/game thread

/xmlapi/thread/<threadid>

• Example: http://www.boardgamegeek.com/xmlapi/thread/381021 [Note: Your browser may interpret this as a request to subscribe to an RSS feed.]
• start: Start article (default = 0)
• count: Number of articles (default and max = 100)
• username: Username to filter for

Retrieve entries from a geeklist

/xmlapi/geeklist/<listid>

• Example: http://www.boardgamegeek.com/xmlapi/geeklist/11205
• comments: Retrieve comments? (default absent, set to 1 if you want comments)

Note: the old "start" and "count" parameters are obsolete and no longer supported. They were required in the original api if you wanted to retreive all items on a geeklist longer than 150 items as that's the most that could be returned on a single api call. Currently however the geeklist xml api returns the entire geeklist (all items) in a single call.

Old Documentation

http://boardgamegeek.com/xmlapi

Discussion thread

http://www.boardgamegeek.com/thread/99401

Games Data XML Snapshot

BGG XML Snapshot