API Documentation → Overview

Introduction

The Gowalla API is another way to access your Gowalla data — one that makes it easy for third-party tools to interact with the service. The API follows the REST conventions. This guide should provide everything you need to implement software that works with Gowalla.

The Terms of Service covers the acceptable use of the service and API. Beyond the legalities, please design your programs to use Gowalla considerately — clients are expected to conform to HTTP 1.1, cache as much as possible, limit the frequency of requests, and include a User-Agent header. If you find a problem with the service or API, please give us a chance to correct it before going public. If you have any questions or issues, feel free to contact support@gowalla.com.

For general questions, announcements, and discussion about the API, please use the gowalla-dev Google Group. For direct contact, email support@gowalla.com.

Authentication

All authentication is handled with HTTP Basic Authentication. All calls must also include your Gowalla API Key in a X-Gowalla-API-Key request header. For example, using the cURL command line program:

curl -H 'X-Gowalla-API-Key: [your API key]'\
 -u userid:password http://api.gowalla.com/

Representation Formats

Most API methods provide JSON responses, served as application/json, encoded as UTF-8. That media type should always be specified in the request’s Accept header. For example, again using cURL:

curl -H 'Accept: application/json' -H 'Content-Type: application/json' \
 -u userid:password http://api.gowalla.com/

Some JSON responses may have keys not documented here. Those values should be considered private, and may change or disappear without notice.

In some cases, records are available in additional formats, like Atom or HTML. You can retrieve records in these formats by changing the Accept header as needed.

Responses and Errors

All response codes are included in the HTTP Status response header. Possible status codes include:

  • 200: Success (upon a successful GET, PUT, or DELETE request)
  • 201: Created (upon a successful POST request)
  • 400: Resource Invalid (improperly-formatted request)
  • 401: Unauthorized (incorrect or missing authentication credentials)
  • 404: Resource Not Found (requesting a non-existent user, spot, or other resource)
  • 405: Method Not Allowed (e.g., trying to POST to a URL that responds only to GET)
  • 406: Not Acceptable (server can’t satisfy the Accept header specified by the client)
  • 500: Application Error

Errors

In most cases, requests that return an “error” status code (i.e., 4XX or 5XX) will contain a short JSON response body explaining the nature of the error (provided the API call asked for a JSON response). For example, a request for a nonexistent user record…

curl -H 'Accept: application/json' -H 'Content-Type: application/json' \
 -u userid:password http://api.gowalla.com/users/eyjafjallajokull

…will return a 404 HTTP status code with the following body: 

{ "error": "Not Found - Shenanigans" }

Other HTTP verbs

Successful POST requests (e.g., to create a new record) will return a status code of 201, include a Location header with the URI of the newly-created resource, and include the JSON representation of the resource in the body of the response.

Successful PUT requests (e.g., to update an existing record) will return a status code of 200, and include the JSON representation of the resource in the body of the response.

Successful DELETE requests (e.g., to delete an existing record) will return a status code of 200 and no body.

URLs and naming

The Gowalla API uses URLs, rather than IDs, as resource identifiers. For example, a request for a single user record will return these properties, among others:

{
  "url":          "/users/1",
  "activity_url": "/users/1/events",
  "stamps_url":   "/users/1/stamps",
  "photos_url":   "/users/1/photos",
  "bookmarked_spots_url": "/users/1/bookmarks"
}

The url property represents the URL of the current resource; the others represent collections of resources related to that user (the user’s stamps, photos, et cetera). This makes it easy to discover related resources. Rarely will you need to build a URL “manually.”

We don't change the URL naming scheme on a whim. But we do reserve the right to change a URL (e.g., giving a resource a different name) if we think it’s necessary. For this reason, it's recommended that API consumers rely heavily on the URLs reported by the record responses, as they're guaranteed to point to the canonical URL for a resource.

Pagination

Most API actions that can return a collection of results abide by a common set of pagination conventions. The returned JSON will contain metadata about the paged result set. For example, requesting a list of spots will return:

{
  "spots":         [], // Array of results
  
  "total_entries": 47, // Number of results across all pages
  "total_pages":   2,  // Number of pages in the result set
  "current_page":  1,  // Page number of the result set
  "per_page":      32  // Number of results per page
}

To request a specific page in the set, pass a page parameter (e.g., /trips?page=2). To change the number of results on each page, pass a per_page parameter (e.g., /trips?page=3&per_page=10).