A few weeks ago, Gowalla released version 4.0 of their app to an overwhelmingly negative response. I myself will be posting a review soon but in this quick post I wanted to share a few tips on how to use the new API that is powering the app as an official API is apparently not coming until Q1 2012.

 In a post entitled "Where the Gowalla API is going" on the official Gowalla Developers Group, it was revealed that most bits of the existing API "should be working" but a version 2 of the API would be coming in 2012 that enables developers to leverage the new features such as stories, lists, likes, guides, and so on. Unfortunately, several parts of the existing API broke on launch of the new app (including OAuth integration which took out nearly all 3rd party apps, trips, and an advanced search API) and some parts were completely removed (such as PubSubhubbub, one of the key things that actually made the Gowalla API a compelling thing to use). I have a number of apps that use the old API and were affected in small ways (I learnt long ago never to make direct calls to the Gowalla API) but there were a few things like trips that I needed direct access to more immediately. So, I spent a few minutes digging into the new Gowalla app and found the new connection details that are required to talk to the new API.

It's actually fairly easy! Firstly, instead of connecting to http://api.gowalla.com/ change the URL to https://api9000.gowalla.com/

Next, there are 4 headers you have to send with every request. 2 of them, "Accept: application/json" and "X-Gowalla-API-Key", were required for the old API but Gowalla have also added an "X-Gowalla-Bruce-Lee" header (with a password so they know it's the Gowalla app using the API) and an "X-Gowalla-API-Version" header which seems to suggest they are taking my advice of 18 months ago and versioning the API rather than just breaking existing apps. So, the full headers you need to send are:

Accept: application/json
X-Gowalla-API-Key: YOUR-API-KEY-HERE
X-Gowalla-Bruce-Lee: l33tkuned0
X-Gowalla-API-Version: 2

If you do that, you should be able to call an API endpoint such as users/bendodson where you'll find a load of new data that isn't in the normal API. That should also give you a good idea of the naming conventions of new endpoints (e.g. /lists rather than /trips). In all of my testing, existing features such as OAuth have worked fine.

As a final example, the trips detail API is still broken on the current API (despite this being "looked into" 2 weeks ago). If you were to request trips/168 you'll get a 404 not found error. This is one of the many broken API calls that is affecting apps that are currently out in the wild. However, if you change your code to use the new URL and the new headers, you can request lists/168 to get full details of the trip you are after. Some of the keys will have changed name but it should be enough to get your app at least up and running.

Obviously, you use all of the above at your own risk. Gowalla are unlikely to break anything immediately as any changes to the headers, endpoints, or keys will break their app. However, there will probably be changes as and when they release new versions of their apps.

I have been very vocal on both the good and the bad points of the Gowalla API in the past. There had been a real effort to alert 3rd party developers to changes in recent months but the new v4 app fundamentally broke important parts of the API (particularly OAuth login) and fixes were slow coming or have still yet to come with regards to the /trips endpoint. Putting an API out for the new app in Q1 of next year is a very long time to wait for something that really should have launched alongside or shortly after the new app particularly as the API does already exist. In short, Gowalla really have a long way to improve in their dealings with 3rd party developers. Personally, I'm moving my apps away from Gowalla and starting to use other services but I'll be posting more about that soon.

Update [25th Oct 2011]: Andrew Dupont responded to this article on the Gowalla Devs Group with:

At any rate, we've fixed the trips API. Let me know if anything's still out of order.

Turns out Gowalla will fix things if you complain enough...