API Documentation → Check In

  1. Checking in
  2. Checkin response
  3. Testing checkins
  4. Fetching checkins
  5. Posting comments to a checkin
  6. Guidelines for using the Check In API
  7. More info

Checking in with the Check In API involves three steps:

  1. Send an authorization request including a scope parameter of read-write
  2. Fetch an OAuth token, again passing a scope parameter of read-write
  3. Send a POST request to /checkins

IMPORTANT: OAuth requests will default to setting authorizations as read-only. To ensure your authorizations don't mysteriously switch from read-write to read-only, always send the proper scope. Note that this doesn't apply to refreshing your tokens, as that process does not change the token's scope.

For more information on the first two steps, refer to our OAuth documentation. The third step is described in detail below.

Checking in

Once your application has a read-write token from a user, it’s time to check in. Let’s suppose your access token is 123abc and the user wants to check-in at Juan Pelota’s, whose Spot ID is 21714. Further, the user’s GPS device has told us we are roughly at latitude 0.30267 and longitude -97.7493. The user enters a check-in message of “Coffee!” and chooses to post the check-in to Facebook but not Twitter.

Here’s how you create that check-in with curl:

curl -H 'Accept: application/json' \
     -d 'oauth_token=123abc' \
     -d 'spot_id=21714' \
     -d 'comment=Coffee!' \
     -d 'lat=30.2679' \
     -d 'lng=-97.7493' \
     -d 'post_to_twitter=0' \
     -d 'post_to_facebook=1' \
     https://api.gowalla.com/checkins

All of the parameters are required.

  • oauth_token are the OAuth token for the user you are acting on behalf of.
  • spot_id is the Spot ID where the user wishes to check-in.
  • comment is the message associated with the check-in. This is what will appear in push notifications, posts to Twitter, and Facebook notifications.
  • lat and lng are the latitude and longitude where the user is checking in.
  • post_to_twitter and post_to_facebook indicate whether Gowalla should post the user’s check-in to those services on the user’s behalf. Not all users have enabled posting to Twitter and/or Facebook on their accounts. Showing users who haven’t enabled this in the options for checking in is confusing. To avoid this, you can infer whether they have enabled this on their account by checking for the can_post_to_twitter and can_post_to_facebook flags returned by /users/me.

Checkin response

If your check-in succeeds, you’ll receive a JSON response like the following:

{
  "created_at": "2010-08-02T16:01:53Z",
  "spot": {
    "name": "Juan Pelota Cafe",
    "image_url": "http://static.gowalla.com.s3.amazonaws.com/spots/...",
    "url": "/spots/21714"
  },
  "detail_html": "<html lang=\"en\">...</html>\n",
  "url": "/checkins/5862017",
  "activity_url": "/checkins/5862017/activity",
  "user": {
    "url": "/users/1165"
  }
}

With this metadata you can show info about the spot the user just checked in to, fetch details about the checkin, and display any rewards or bonuses the user received for their checkin.

An important part of the Gowalla experience is receiving rewards, pins, and bonuses. These are rendered as HTML screens that the client pages between using JavaScript. To provide the user with a good experience, these screens should be displayed by your application after the user has checked in. The detail_html field in the checkin response contains the HTML to render.

Testing checkins

When you are developing and testing your application, you don’t want to create actual checkins. Instead of posting to https://api.gowalla.com/checkins, you can post to https://api.gowalla.com/checkins/test. This endpoint takes the same parameters and performs the same validation as the real endpoint; however, it does not create the checkin, check trips, or post to Twitter/Facebook.

Use the test endpoint while you are developing your app. Once it’s ready to ship, change to the real checkin endpoint.

Fetching checkins

After you’ve created a checkin, you’ll probably want to display data about it or let the user follow their check-in to see if anyone leaves a comment. You can do so by fetching the URL returned in the checkin response. Using the example above, you’d fetch the checkin like so:

curl -H 'Accept: application/json'
    'https://api.gowalla.com/checkins/5862017?access_token=1234567890abcdef'

The response will look like this:

{
  "created_at": "2010-08-02T16:01:53Z",
  "spot": {
    "name": "Juan Pelota Cafe",
    "image_url": "http://static.gowalla.com.s3.amazonaws.com/spots...",
    "url": "/spots/21714"
  },
  "url": "/checkins/5862017",
  "activity": [],
  "type": "checkin",
  "activity_url": "/checkins/5862017/activity",
  "message": "coffee!",
  "user": {
    "_is_friend": true,
    "image_url": "http://s3.amazonaws.com/static.gowalla.com/users/...",
    "url": "/users/1165",
    "last_name": "Keys",
    "photos_url": "/users/1165/photos",
    "first_name": "Adam"
  }
}

Posting comments to a checkin

Given the URL for a checkin, you can post comments to it. You could post to the checkin from the previous example like so:


curl -H 'Authorization: Token token="abc123" \
     -H 'Accept: application/json' \
     -d 'message=first!' \
     -d 'post_to_twitter=0' \
     -d 'post_to_facebook=0' \
     https://api.gowalla.com/checkins/5862017/activity

If you pass an empty message, the OAuth token is for a user who is not friends with the user who owns the checkin, or there was some other problem with the comment, a 406 Unacceptable response is returned. Otherwise, an empty JSON hash is returned with a 201 status code.

Guidelines for using the Check In API

Gowalla aspires to connect real people with real places. Our goal has always been for people to go out and explore both locally and around the world.

As such, the Check In API is primarily intended for use by applications and services designed for mobile devices. Thoughtful uses of the API by applications and services designed for location-aware browsers on the desktop are also permitted. We encourage developers to use the following guidelines when creating applications that use Gowalla’s Check In API.

  • Encourage users of your application to check in at places they are actually located.
  • Avoid incentives or game mechanics that reward checking in from distant locations.
  • Never “auto check-in” a person without their explicit permission. This is seriously uncool.
  • Encourage social interaction over bot-like behavior.
  • Rapid, repeated check-ins with the intent to automate the location and swapping of items will not be tolerated.
  • Go easy on the API. Cache data where you can, respond to error messages, and be thoughtful about your user experience.

Applications that disregard the guidelines above risk violation of Gowalla’s Terms of Service and may have their API access suspended without warning. So keep cool, my babies.

More info