Journey complete: a BoardGameGeek collection Tableau web data connector

Several months (!) after setting myself the challenge of becoming familiar with how to create a Tableau Web Data Connector, the good news is…it’s done! Well, done enough that I now understand how to create web data connectors should I ever need one in reality anyway.

As planned, its a connection via the BoardGameGeek API to your very own board game collection, if you have catalogued one at that site. For the uninitiated, BoardGameGeek is an amazing site if you’re the sort of person that likes boardgames, and, yes, cataloguing.

So, for starters, if you have indeed got a collection catalogued, or want to analyse someone else’s collection, then you can now point your Tableau Desktop software to a web connector at http://amedcalf.github.io/BGGConnector.html

Update: As of January 2018, this connector doesn’t appear to work any more – claiming an extract cannot be created. Apologies.  I will leave the info below for historic interest. My guess would be that either the underlying BGG API changed, or that Tableau’s updating to WDC version 2 means that some modification is needed.

Important / annoying note (explained below): BEFORE you do this, go and visit the below link in your web browser to make sure your BGG collection is not going to be stuck in an API queue.

https://boardgamegeek.com/xmlapi2/collection?username=Adam121

replacing the “Adam121” with the username you’re interested in. If you get a message about queues, caches or other errors, wait a few seconds and try again, until you end up with some unpleasant looking XML code that looks something like a whole string of this.

 Yes, this is not user friendly and would not be acceptable in a “production” environment, but this is just for fun; I’ll explain more below.

Once you’ve done that, go back into Tableau.

Once you have entered http://amedcalf.github.io/BGGConnector.html into the web data connection datasource part of Tableau (see Tableau’s instructions here), you should get a basic prompt to enter your BoardGameGeek username. You can test it with “Adam121” if you like, without the quotes. Do that, and up should pop the relevant collection ready for usage in Tableau.

Here is a description of the fields you’ll be presented with:

• Boardgame Name: Textual name of your board game
• Image Thumbnail URL: text URL of a small image relating to the boardgame, usually its cover.
• Image URL: same as above, but a big version.
• Last Modified: date the record was last changed.
• Year Published: the year the game was published.
• Plays: how many times you logged that you played this game.

Then there’s a series of flags that are set to either 0 (false) or 1 (true). These are:

• For Trade
• Owned
• Preordered
• Previously Owned
• Want
• Want To Buy
• Want To Play
• Wishlist

and are all attributes you can input yourself per game with the BGG collections feature.

Whilst it is based on the BoardGameGeek API, I should also to give maximum thanks to the BoardGameGeek user “Strathmeyer”, whose past repurposing of the BGG API into CORS-enabled JSON is what I ended up using as my source, rather than the API directly. When I come to document my journey, I’ll go through why.

One thing to note: if you try it on a username and it doesn’t work (perhaps giving a “typerror”) then this is probably down to the caching of the API on the server. BoardGameGeek queues API calls for collections that haven’t been requested in a while, and the JSON source seems to cache the “in a queue” response meaning that no data appears.

You can see if this is why you’re having problems if you go to this link, putting the BoardGameGeek user ID you’re after after the last equals sign of the link:

http://bgg-api.herokuapp.com/api/v1/collection?username=YOURUSERNAME

If it returns the message “Your request for this collection has been accepted and will be processed. Please try again later for access” then you’re in the queue. And it seems to cache the fact you’re in the queue, which is why you should go visit https://boardgamegeek.com/xmlapi2/collection?username=YOURUSERNAME before you do anything else, even visit the herokuapp link.

I haven’t taken the time to come up with a nice solution for this, but this is what worked for me. Obviously it’s a very unsuitable requirement should this be the mainstay of someone’s production system, but I’m afraid I was just playing about to see what works 🙂

So what can you do with this, except poke around for fun?

Well, ever since the great-yet-terrible event that was the downsizing of my infeasibly oversized board games collection, I don’t really have more than would fit on a single screen of BGG to be honest, and I can’t usually find many people to play them with me anyway (insert sympathy sound effect). But if you had a bigger collection, you might find it useful to answer such questions as “How many board games do I own?”, “Which board game have I played the most?”, “How many board games do I want to buy?” and so on. If so, please enjoy!

Just to prove to myself that it works, here’s an example very simple, quite pointless, dashboard that displays my collection and allows you to click on the name of a game in it, and see what the box looks like. Feel free to click through and play with it.

What’s next? Well, the point of the exercise was not really to find a way to list the remnants of my board games collection – but rather to learn something new, and document something of the journey I went through doing so, warts and all. With that in mind, I’ll be writing a few notes as to the trials and tribulations I went through in creating this, for future reference if nothing else.