BGG XML API redirected from XML API

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).

Related wikis: Data Mining, and BGG XML API2

Note: BGG throttles the requests now, which is to say that if you send requests too frequently, the server will give you 500 or 503 return codes, reporting that it is too busy. Currently, a 5-second wait between requests seems to suffice.

/xmlapi/search

• Parameters:
  • search: String to search for (required)
    • Syntax: /xmlapi/search?search=<searchString>
    • Example: https://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: https://boardgamegeek.com/xmlapi/search?search=Crossbows%20and%20Catapults&exact=1

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

• Example, single game: https://boardgamegeek.com/xmlapi/boardgame/35424
• Example, multiple games: https://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: https://boardgamegeek.com/xmlapi/boardgame/35424,2860?comments=1
    • Optional: page: You can use page to increment the results (set it to the page of results you want, 1 by default)
  • stats: Include game statistics (set it to 1, absent by default)
    • Syntax: /xmlapi/boardgame/<gameId>?stats=1
    • Example: https://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: https://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: https://boardgamegeek.com/xmlapi/boardgame/35424,2860?historical=1&from=2009-01-01&to=2009-03-17

/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.

The XMLAPI will place requests for geeklists and user collections into a queue to be processed by backend servers. When this happens, the request will result in an HTTP response of 202 to indicate the request has been queued and is pending processing. These collection requests will result in an HTTP response of 200 along with the XML data once the server has the data available (See Export collections has been updated (XMLAPI developers read this) for details).

• Example: https://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: https://boardgamegeek.com/xmlapi/collection/zefquaavius?own=0 - games in zefquaavius' collection that he doesn't own
    • Example: https://boardgamegeek.com/xmlapi/collection/zefquaavius?own=1 - games zefquaavius owns
  • rated
    • Syntax: /xmlapi/collection/<username>?rated=<0,1>
    • Example: https://boardgamegeek.com/xmlapi/collection/zefquaavius?rated=0 - games in zefquaavius' collection that he has not rated
    • Example: https://boardgamegeek.com/xmlapi/collection/zefquaavius?rated=1 - games zefquaavius has rated
  • played
    • Syntax: /xmlapi/collection/<username>?played=<0,1>
    • Example: https://boardgamegeek.com/xmlapi/collection/zefquaavius?played=0 - games in zefquaavius' collection for which he has never logged any plays
    • Example: https://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: https://boardgamegeek.com/xmlapi/collection/zefquaavius?comment=0 - games in zefquaavius' collection upon which he currently has comments
    • Example: https://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: https://boardgamegeek.com/xmlapi/collection/zefquaavius?trade=0 - games in zefquaavius' collection he is not offering for trade
    • Example: https://boardgamegeek.com/xmlapi/collection/zefquaavius?trade=1 - games zefquaavius is offering for trade
  • want
    • Syntax: /xmlapi/collection/<username>?want=<0,1>
    • Example: https://boardgamegeek.com/xmlapi/collection/zefquaavius?want=0 - games in zefquaavius' collection of which he does not want (i.e. He's not looking to add it his actual collection.)
    • Example: https://boardgamegeek.com/xmlapi/collection/zefquaavius?want=1 - games for which zefquaavius wants to acquire
  • wantintrade
    • Syntax: /xmlapi/collection/<username>?wantintrade=<0,1>
    • Example: https://boardgamegeek.com/xmlapi/collection/zefquaavius?wantintrade=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: https://boardgamegeek.com/xmlapi/collection/zefquaavius?wantintrade=1 - games for which zefquaavius is willing to make a trade
  • wishlist
    • Syntax: /xmlapi/collection/<username>?wishlist=<0,1>
    • Example: https://boardgamegeek.com/xmlapi/collection/zefquaavius?wishlist=0 - games in zefquaavius' collection that are not on his wishlist
    • Example: https://boardgamegeek.com/xmlapi/collection/zefquaavius?wishlist=1 - games in zefquaavius' wishlist
  • wanttoplay
    • Syntax: /xmlapi/collection/<username>?wanttoplay=<0,1>
    • Example: https://boardgamegeek.com/xmlapi/collection/zefquaavius?wanttoplay=0 - games in zefquaavius' collection which he has no pressing desire to play
    • Example: https://boardgamegeek.com/xmlapi/collection/zefquaavius?wanttoplay=1 - games zefquaavius currently wants to play
  • wanttobuy
    • Syntax: /xmlapi/collection/<username>?wanttobuy=<0,1>
    • Example: https://boardgamegeek.com/xmlapi/collection/zefquaavius?wanttobuy=0 - games in zefquaavius' collection he doesn't wish to buy
    • Example: https://boardgamegeek.com/xmlapi/collection/zefquaavius?wanttobuy=1 - games zefquaavius wishes to buy
  • prevowned
    • Syntax: /xmlapi/collection/<username>?prevowned=<0,1>
    • Example: https://boardgamegeek.com/xmlapi/collection/zefquaavius?prevowned=1 - games zefquaavius previously owned
  • preordered
    • Syntax: /xmlapi/collection/<username>?preordered=<0,1>
    • Example: https://boardgamegeek.com/xmlapi/collection/zefquaavius?preordered=1 - games zefquaavius has pre-ordered
  • hasparts
    • Syntax: /xmlapi/collection/<username>?hasparts=<0,1>
    • Example: https://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: https://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: https://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: https://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: https://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: https://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: https://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: https://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: https://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: https://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: https://boardgamegeek.com/xmlapi/collection/zefquaavius?minplays=50 - games zefquaavius has played 50 or more times
  • maxplays
    • Syntax: /xmlapi/collection/<username>?maxplays=<number>
    • Example: https://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: https://boardgamegeek.com/xmlapi/collection/zefquaavius?showprivate=1 - include private info zefquaavius has listed, provided you're zefquaavius
    • Example: https://boardgamegeek.com/xmlapi/collection/zefquaavius?showprivate=0 - If you're zefquaavius, see what everyone else sees when viewing your collection: No private info

/xmlapi/thread/<threadid>

• Example: https://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

/xmlapi/geeklist/<listid>

• Example: https://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.

https://boardgamegeek.com/xmlapi

OLD: https://boardgamegeek.com/thread/99401
NEW: https://boardgamegeek.com/guild/1229

BGG XML Snapshot

• abecorn - Math Trade/Direct Trade Service
• OLWLG - "On-Line Want List (editor &) Generator" Math Trade Tool Set
• Historical Marketplace Sales Data
• minibgg.com - BGG for mobile browsers
• Miss the correlation tool? Check here!
• zefquaavius' math trade tools, high-correlation geekbuddy maintenance tools, Morse Hotness tools, and sundry other utilities.
• Generate a PDF with all your games
• Friendless's BGG Extended Stats - Thread here.
• BGG2nanDECK software for trasforming XML info in CSV files (for nanDECK): tutorial and features.
• BoardGameGeek application for Android (temporarily unavailable, see App's Guild)
• monteslu's Mobile BoardGameGeek site for Android, iPhone, iPod Touch, iPad, etc.
• monteslu's rating charts and user ratings deviance
• justmarks's MobileBGG application for Windows Phone 7
• Finchley Games Club use the API to display members' games collections.
• Mini-Geek One more site for forum browsing on mobile devices (IOS and Android)
• What is your collection or friends collection worth?
• B.G.Jeeves is an Android app used to tracking your collection and recording plays. (It only uses "get" requests from the API, nothing gets pushed back right now, but that may come later.
• Dazeysan's bookmarklet for SPLU (Splendiferous Play-Logging Utility) - Allows users to log plays faster by providing clickable player names, concomitant expansion logging, and a different GUI.
• CaptainJax's BGG Last Plays Windows Phone app for keeping track of when you last played the games you own: New BGG-Related Windows Phone App
• BoardGameGeek an iOS app by Ryan Christianson
• Solitaire Games On Your Table (SGOYT) Aggregator - web archive and stats of all SGOYT entries since May 2013 by the Ones Upon a Game blog.
• Wargames On Your Table (WGOYT) Aggregator - web archive and stats of all WGOYT entries since October 2009 by the Ones Upon a Game blog.
• Similarboardgames.com - suggestion tool for similar boardgames, mobile friendly
• TheGameSteward.com - displaying RPG data with games.

XML API Enhancements