Introduction

The purpose of this wiki is write some documentation on how to use the GowallaPHP library in projects. We are breaking down this Wiki into two topics - basic Authentication and OAuth Authentication.

Please note: GowallaPHP 2.0 doesn't include support for basic HTTP Authentication.

Basic Setup

Basic Setup has been stripped out in Version 2.0.

OAuth Authentication

The key attributes that you will need after you sign up for an OAuth account is the following:

* Client ID (Known as your API Key)
* Secret Key
* Callback URL

Once you have these your ready to start making API calls.

Let's get OAuthing!

There a few new method that you can use for OAuth with this library. Let's walk through them.

function generate_url(false)

This function will generate a URL to send to Authorize your application with their Gowalla account. This works very similar to Twitter's Authentication. If you pass true to the variable you will enable use of the checkin method from Gowalla. Otherwise - leave it the default of false.

After the user authorizes the application, it redirects back to the callback_url parameter that you set during installation with a code query string.

function storeToken($code, false)

This function takes the query string value of code and does all the magic behind the scenes to get your access token and store it. After this stage is complete you can start making API calls as normal. The second parameter enables you to use the checkin API method. If your application isn't using the checkin method from the Gowalla API, then you can leave this as the default false. Otherwise - make this value true to enable the checkin method.

function getToken()

This function will return an array of useful information about the current session. Tokens are set to expire in 2 weeks from creation so this function will return the following information:

['access_token'] = Access Token to make calls. You might want to save this in a session or a database.
['refresh_token'] = A token used to refresh after it expires. You will need to save this in your DB or session if you want use it again.
['refresh_time'] = The Date of Expiration for the Token. You will need to save this in order to use their account again.
['username'] = the Gowalla username of the authenticated user. This might be blank if you are re-authing users from a DB token.

If your token is expired - the library will automatically request a new one so you won't have to deal with that situation. It's mainly for information to the user.

function setToken($access_token, $refresh_token, $refresh_time)

This function will allow to use a saved access token, refresh token and refresh time in the GowallaPHP class. It's easy to do - say you have got the user's refresh and access token and stored them in a session. To enable them in the instance of GowallaPHP you do:

$myGowalla->setToken($_SESSION['access_token'], $_SESSION['refresh_token'], $_SESSION['refresh_time');

This is optional and only for people that want to use the full functionality of the class. This allows you to store in a database or session the access token and refresh tokens for later use. IMPORTANT: refresh_time, must be UNIX TIMESTAMP FORMAT. You can do this:

date("U", strtotime($refresh_time));

Check-In API

With version 1.5 - we've enabled checkin method from Gowalla's API. It's pretty simple to enable in your application. Just generate a URL using the generate_url() function, but pass it a true variable like so:

echo generate_url(true);

After you get your $code and use the storeToken function, just pass it another variable of {{{ true }} like so:

$myGowalla->storeToken($_GET['code'], true);

Then you'll be all set to start calling the Check-In Methods!

Types of Check-In Method

We have two types of check-in method, check_in_test and check_in . Gowalla offers the checkin test to allow for developers to test their checkins. Let's explore the variables for these functions - as they are they the same.

function post("/checkins", array("lat"=> , "lng"=>, "spot_id" => , "comment" =>, "post_to_facebook"=>, "post_to_twitter"=>)

The only required arguments for this function are $lat , $lng , $spot_id . All other fields are optional. $post_to_facebook and $post_to_twitter are Boolean variables.

Once you call your function, make sure you wrap your calls in a {{ try , catch }} phrase and use the new Checkin Exception GowallaExcetion . If you are successfully - you will get a nicely format JSON response like below:

{
  "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"
  }
}

Sample Code

I would refer to the example.php provided in the package for an example on how to authenticate and make calls.

Making API Calls

At this point you have created an instance of the GowallaPHP class. Now - lets find out what we can call. Below is the list of all the API functions that you can use. Some of these are documented and some are not documented.

/* Utilities Functions */
function getUserAgent() // Gets the User Agent associated with instance

function setUserAgent($user_agent) // Sets the User Agent of the the associated instance

/* Other Functions */

In GowallaPHP 2.0 - all you need to do is use the endpoint URL to make the "GET" and "POST" call.

For example, to get the authenticated user:

{{{
$me = $myGowalla->get("/users/me");
}}}

If you need to pass parameters to get a GET call, pass them as an array:

{{{
$me = $myGowalla->get("/users/me", array("someArgs" => "coolness");
}}}


= Parsing Returned Data =

Each attribute in the response is returned via a JSON array. All the attributes are the same as documented on the Gowalla API Documentation. 

If you more information on how what the attributes are for each function - you can review them at the Gowalla API documentation website (http://api.gowalla.com/api/docs).

You can extract the results for a query by doing 1 of the following:

{{{

// Single Entry
$me = new GowallaPHP("sampleKey");

$users = $me->get("/users/gregavola");

echo $users->first_name;

// Multi-Entry
$me = new GowallaPHP("sampleKey");

$user_stamp = get("/user/gregavola/stamps");

foreach($user_stamp->stamp as $stamp)
{
    echo $stamp->name;
}

}}}

= Catching for Errors =

Since using an API means that you may run into problems - we've include custom errors in the GowallaPHP Library. We recommend that you wrap all calls in a try/catch statement to catch for these errors. See below for example:

{{{
$me = new GowallaPHP("sampleKey");

try
{
  $user_stamp = $me->get("/users/gregavola/stamps");

  foreach($user_stamp->stamp as $stamp)
  {
    echo $stamp->name;
  }
}
catch(GowallaException $e)
{
   echo $e->getMessage();
}

}}}

The following at the total list of Exceptions:

{{{
GowallaException - This is called if anything occurs in the system that is wrong. It's catch all clause.
}}}


If you have any questions, feedback or praise, send me a tweet at @<a href="http://twitter.com/gregavola">gregavola</a>.