Wouldn't it be nice if you could access geek data in a programmatic way? It would be handy if your game tracking tool could look up game IDs based on name, or get a machine readable version of some game statistics without having to do all that screen scraping, right?

Well, now you can. It's starting off with a limited set of features, but I wanted to get feedback and requests before I spend time building parts that are going to be less used. So, to start off here's what you can get via the new XML API:

- Search for games by name
- Get basic information on a game
- Get statistics on a game (rank, etc)
- Get comments on a game (listed by username)

There are currently two XML API URLs of relevance:

http://boardgamegeek.com/xmlapi/search
http://boardgamegeek.com/xmlapi/game/[gameid]

Both take some parameters as URL encoded components of the query string.

/xmlapi/search takes a single required parameter "search" which is what to search for and an optional parameter "exact", which should be set to 1 to get exact search. Search is always case insensitive.

For example:

http://www.boardgamegeek.com/xmlapi/search?search=euphrat
http://www.boardgamegeek.com/xmlapi/search?search=ra&exact=1

/xmlapi/game/[gameid] has no required parameters other than the gameid which is part of the URL. It has two optional parameters, "stats" which adds a statistics element to the game xml, and "comments" which adds a comments element listing all comments on the game. For example:

http://boardgamegeek.com/xmlapi/game/3727
http://boardgamegeek.com/xmlapi/game/3727?comments=1
http://boardgamegeek.com/xmlapi/game/3727?stats=1
http://boardgamegeek.com/xmlapi/game/3727?comments=1&stats=1

So, what additional information should be exposed. I'm interested in suggestions and feedback, but I will add a few qualifiers:

- I'm more interested in suggestions involving game data than forums/geeklists.
- I'm more interested in specific real use cases than theoretical "it would be neat if..." cases. That is, someone who says: "I have a free game play tracking tool and I will use the /xmlapi/search interface to sync with bggids, but I could really use..." is more likely to get done than someone who says "It'd be neat to have a list of image URLs for a game".
- Don't abuse the system. This isn't license to slam the servers. Self regulate your hit rate. There are no limits in place now, but they'll get added if it becomes a problem.
- Stuff that will be low impact on the servers and likely to be useful even when only hit occasionally will be more likely to be implemented than stuff that it likely to get reloaded constantly by programs.
- Because of various database constraints, some things are simply easier than others. Because of time constraints, these will get implemented first. Don't take it personally if the thing you want doesn't get implemented.

So, what would be useful to add?

What are you going to do with the initial stuff I've given you?

Oops!

XML Parsing Error: not well-formed
Location: http://www.boardgamegeek.com/xmlapi/game/12962
Line Number 8, Column 39:
<publisher publisherid="83"><name>R&D Games</name>
---------------------------------------------^

Looks like you have to escape the data...

~Simon

Fixed.

Hi Matthew,

Request 1
I would like to see the addition of a reference to the (thumbnail) image with most recommendations for the game. For example,
<game gameid="20847">
...
<name primary="true">Take Stock</name>
<thumbnail>
http://files.boardgamegeek.com/bggimages/pic102092_t.jpg
</thumbnail>
...
</game>

Request 2
I also want to be able to generate a list of the games in my collection. (Filters would be a nice addition, but not immediately necessary).


Planned Project
I plan to use this to be able to create a "My Game Collection" database on my Palm PDA. My Palm App will allow me to filter by number of players, etc. to generate some recommendations for games to play.

On-line Games status
I would like to be able to get an XML feed for the current status of my online games. For example:

http: //boardgamegeek.com/xmlapi/onlineGameStatus?userid=simonh

(the userid parameter could be dropped if you used my login cookie, I guess)

I would like the data to contain the name of the game, the players, whose turn it is (a flag if it is my turn?) and a link that would take me to the game, etc.

I would create (and publish) a Google Desktop 2.0 Sidebar Plug-In that polled the server once every 5 minutes to display the current state of my games. (Is this an "excessive hit rate" ?).

~Simon

Excellent! I'll definitely take a look when I get home.

For clarification I'm assuming that you're referring to CDATA tags?

I'll add something like this soon.



I'll add filtering eventually, but here you go:

http://boardgamegeek.com/xmlapi/collection/simonh

Currently, it only reports gameids, ratings and comments for owned games. I'll add more filtering options later.



Cool.

Wow, that was fast! Perfect!!
Thanks Matthew.

~Simon

I just want to say that however people use this, this feature is so critically important it is hard to overstate how important it is. Thank you, thank you.

And "however people use this" is exactly the point; you will see some amazing things come out of this.

Yehuda

I wasn't even going to request it, but thanks for adding the collection tool. I'll be using that to sync my personal game database ratings with my Geek ratings. Very cool. Thanks!