The latest social media craze on the web today is focused around location-based social networking. Companies such as Gowalla and most notably Foursquare run off a social grid check-in system. For every visit to your local shopping plaza, pizza shack, park or school you can update your status and earn points towards unlocking badges.
The network pivots traveling the globe into a digital game of sorts. Through Foursquare’s mobile app you can run your own user account, update check-ins to Twitter or Facebook, upload photos, and so much more! The numbers have been growing rapidly and Foursquare’s community circles the world.
When you first start developing over Application Programming Interfaces there are many hurdles to overcome. Through some fantastic articles Google searches hold the answer to a lot of your basic questions on PHP and API connections.
When discussing Foursquare’s API I highly recommend their Google groups forum. It comes with a few FAQ pages and great user discussions archived over time. More specifically they offer the web API documentation in an elegant way for novice and professional alike.
To get started you’ll need a simple PHP web setup. If you’ve got remote server space you could alternatively host everything elsewhere. However if you’re impatient and don’t need Internet access it’s much simpler to install a local server environment.
External Libraries and OAuth
We only need a few external files to work with Foursquare efficiently. When building an OAuth application there are many simple steps required to get started. This is an open platform built with simplistic standards in mind.
Below is a general overview for an OAuth connection:
- Obtain request key and secret from Foursquare API
- Add login/authentication link somewhere on website
- User clicks link. Directed to Foursquare and approves/rejects access to their account from 3rd party application
- Store now secured key and secret to call requests from Foursquare database
You will need a Foursquare account to obtain your key and secret in the first place. It’s a free signup, and if you wish to work on the API I’m sure you’ve already had an interest in the application! Once logged in check out their OAuth registration form to create your new app.
You’ll need to give three (3) bits of data before obtaining your unique key and secret string pair. The app name, website URL, and return URL. The first two are fairly self explanatory while the return URL is simply the page Foursquare will re-direct users back towards after authentication is complete.
The final step after account creation is figuring out which external libraries to use. The simpler and easier we can access bits of data, the quicker our application will run. Github is a fantastic community where developers share their bits of code with the world.
Specifically user jmathai’s Foursquare async library is perfect for what we’re doing. You can download the package directly from that page. Inside you’ll find a few files, namely the core libraries we’ll need to be working with. Listed below:
Inside our index.php file there are a few fields requiring some input. Towards the top we’ve got two (2) variables named $consumer_key and $consumer_secret. Inside you’ll want to set the string value to whatever Foursquare has set up in your OAuth application settings.
The second file we need to edit is callback.php. This will handle a generic callback from Foursquare and allows us to pull information about the authorization request (acceptation/rejection). Towards the top of this file you’ll see the same variables requesting the same set of values – seemingly redundant, but useful to keep scripts independent.
Pulling User Data
Try loading your index.php file inside any browser from your local server. You should see a small page with a login link – clicking this will redirect to Foursquare where you can choose to allow or deny the connection to your application. Upon acceptance you’ll be re-directed towards your callback URL and can pull user data at will!
As a brief example let’s examine checkin history. Through these few lines of code we can easily pull the past few checkins from any authorized account and display them onscreen (or possibly store them in a database for easy access!)
// call 4sq data
$fsqUsrHistory = $foursquareObj->get_history();
We first set a unique variable $fsqUsrHistory to hold our history object. This should return an array containing specific information about each of the previous checkins from the target account. The PHP
print_r() function will display the response array in plaintext on the screen.
This has been a basic look into getting started with Foursquare’s API. OAuth is a very powerful open protocol for connecting into larger social communities. It offers the most secure solutions for both users and webmasters.
If you’re still a bit lost that’s to be expected at first. Try downloading the package from Github and messing around with some of the files. Even rudimentary PHP skills will suffice when working with these libraries, so it’s difficult to mess things up.
The Foursquare Developers center is an amazing tool for newbies. Scour the resources and look up and function calls you may be interested in working with. Similarly the official OAuth website has some terrific readings outlining the purpose and practical solutions for the protocol.