Introduction to the Foursquare API

Create a basic application using PHP


Location-based services like Foursquare are all the rage. If you haven't heard about them yet, you will. It seems that everywhere you turn, people are using Foursquare, Gowalla, Loopt, and other tools to "check in" to their favorite locations, share tips with other users about favorite drinks or dishes, and share all of this activity on other services like Twitter and Facebook.

As a developer, you have to know this stuff. Social, and specifically, location-based services that use social platforms, represent a huge growth area for web and mobile developers. Most of these services use some kind of RESTful service you can use to request JavaScript Serialized Object Notation (JSON) or XML data. Some, such as Facebook, don't require much authentication, while others, like Foursquare, have some feeds that do require authentication and some that don't.

For the purposes of this article, I assume that you know something about PHP, but that's about it. I walk through everything else at an easy pace — accessing a Foursquare feed, working through the result set, and cleaning it up. The sample application you build at the end of the article is simple: provide Foursquare with geolat and geolong coordinates and see how many people are currently checked in at nearby locations. Because I live in Austin, Texas, I think it would be interesting to enter coordinates for a spot on Sixth Street and see what's happening in nearby places.

I chose this particular option for two reasons. The first is because it's the simplest feed to access, but unwrapping it gives you a pretty good preview of what you can expect with other feeds. The second is that it doesn't require authentication — after all, you're not looking for details on who is actually checked in, just raw counts. The venues public feed provides a great deal of functionality within the scope of this article.

What is Foursquare?

Foursquare is a social location service that allows users to explore the world around them. Users can download the Foursquare application to their iPhone, Blackberry, or Android phone and sign up for free, then connect their Foursquare accounts to their other social media accounts.

After users download the free application and connect on Facebook or Twitter, they can connect with their friends who are also active on Foursquare. Whenever they or their friends check in to a place (that is, they're at a location and they tell others that they are there), the message is broadcast to their friends via Twitter or Facebook.

When a user checks in enough times, that user becomes the mayor of a location, which may or may not give the user access to special offers, depending on the business running a location. For example, a coffee shop might extend a free drink to anyone who becomes a mayor. Users can also earn badges as they explore and check in to locations, leave tips for other users (for instance, "The margaritas here are great!"), and may even have the opportunity to create locations that haven't appeared yet on the service.

Figure 1 is a screenshot of the Foursquare home page on the Web.

Figure 1. Foursquare home page
Image shows screenshot of Foursquare home, showing menu options,                     download options and recently reported activity
Image shows screenshot of Foursquare home, showing menu options, download options and recently reported activity

Foursquare launched its API in November 2009, allowing application developers to extend the platform in interesting ways. Developers can build location management tools, custom search engines, and even games and other tools that interact with the Foursquare API. For example, you could build a geolocation game that allows players to also check in to Foursquare locations as a natural byproduct of normal gameplay.

With this view of Foursquare in mind, let's take a look at the Foursquare API.

A quick tour of the Foursquare API

The Foursquare API allows application developers to interact with the Foursquare platform. The API itself is a RESTful set of addresses to which you can send requests, so there's really nothing to download onto your server. That being said, in this article, you use a set of PHP libraries to help simplify requests and responses, but this is an entirely optional step.

You can currently request output in XML or JSON format, making requests to URLs that look like this: If you don't use an extension on your request, then XML is served back to you. A request to results in an XML output.

There are both GET and POST methods you can use, which means you aren't just limited to reading from feeds, you can also do useful stuff like checking in and creating locations using the API. As for rate limits, your application is limited to 200 requests per hour per method, so you probably want to implement some kind of result caching to "play nice."

For the most part, you want to use basic or OAuth authentication to take full advantage of the various methods and services. The example in this article (/venues) doesn't require any authentication to get started, but it does have additional features available to those who do use authentication.

What can you do with the API? Table 1 summarizes the major methods. For more details, please read the API documentation (Related topics).

Table 1. Summary of Foursquare API methods
MethodSummaryURLParametersHTTP method(s)Authentication?
CheckinsReturns a list of recent check-ins from friends., geolongGETYes
CheckinAllows you to check in to a place., venue, geolat, geolong (others)POSTYes
HistoryReturns a list of check-ins for the authenticated user., sinceidGETYes
User detailReturns profile information for a given user ID., twitter, badges, mayorGETYes
FriendsReturns a list of friends.
VenuesReturns a list of venues near the area specified., geolong, l, qGETNo
Venue detailReturns venue data for a given venue ID.
CategoriesReturns a hierarchical category list.
Add venueAllows you to add a venue., address, city, state, zip, phone, geolat, geolong, othersPOSTYes
Propose venue editAllows you to flag a venue for edit or update., name, address, city, state, zip, phone, geolat, geolong, othersPOSTYes

There are a whole bunch of other API methods that relate to friends, testing authentication, flagging locations for different reasons, gathering and creating tips, etc., but I think you get the general idea.

Building your own PHP application

Now that you've had the nickel tour of the Foursquare API, you can get down to business and build a simple application. As I hinted at in the introduction, what I want to do is create a view that tells me how many people have checked in to locations centered around the Sixth Street bars in Austin. Hey, there's no sense for me driving all the way downtown and finding parking if nobody is actually hanging out down there!

Although it may appear frivolous to use the Foursquare API for this purpose, please note that you can take this basic idea and use it in a variety of contexts. For example, you may want to track how many conference attendees are checking in to local venues while they're in town or how many people are checked in to various conference breakout sessions.

For the purposes of this article, I break the process down into three major pieces:

  1. Download the helper libraries
  2. Create a basic feed
  3. Create a cleaned-up web page with the feed contents

Download the foursquare-async library

Although you really don't need much of a wrapper for the Foursquare API, it's a good idea to download the marvelous foursquare-async library from GitHub (see Related topics). It provides a handle of files that let you work with most of the methods available to you via the API.

The download includes a readme file, a license document, and three PHP files:

  • EpiCurl.php
  • EpiFoursquare.php
  • EpiOAuth.php

Put all three PHP files into a directory called lib at the root of your project and move on to the next step in the application construction.

Create a feed

Next, create a file called feed.php and place it in the root of your project. In this file, you use the require() function to pull in all the Epi*.php files you downloaded and put in the lib folder.

Then you instantiate a new epiFourSquare object and use that object to connect to the venues.json feed, passing in any necessary parameters for geolat, geolong, and a limit of 50 results.

Finally, you use json_encode() to transform the incoming JSON feed into a PHP data object and save it as an array. Of course, to be safe about all of that, you wrap the whole thing in try {...}exception.

If you don't run the feed through json_encode(), you end up processing something such as the feed shown below.

Figure 2. Raw JSON feed
Image shows raw JSON feed, showing code as unformatted text
Image shows raw JSON feed, showing code as unformatted text

This is fine for some people, but you have to admit that the PHP data object shown in Figure 3 is a bit easier to figure out.

Figure 3. PHP data objects from JSON
Image shows PHP data objects from JSON, showing formatted code that is easy to read
Image shows PHP data objects from JSON, showing formatted code that is easy to read

Listing 1 shows the entire bit of code.

Listing 1. Connecting to the Foursquare venues feed

$fsObj = new EpiFoursquare();
	$venues = $fsObj->get_basic('/venues.json', 
			array('geolat' => '30.268056',
			'geolong' => '-97.741381',
			'l' => '50'));
	$venues_array = json_decode($venues->responseText);
}catch(Exception $e){
	echo "Error: ". $e;

This is nothing terribly complex, just 15 lines of code to get a feed of venues and check-in counts. Please note that the geolat and geolong coordinates in the example match the vicinity of the Driskill Hotel in downtown Austin — I'm using that locale as a convenient central point because many downtown venues are close to it.

Create a web view

At this point, what you have is a JSON feed that has been converted to a PHP data object. This is useful for the PHP programmer, but nearly useless to anyone else. What you need to do is pull all of this into a web page that mere mortals can use.

To this end, create an index.php file in the root of your directory. Use any Cascading Style Sheets (CSS) and JavaScript frameworks and design elements you feel comfortable with. For instance, notice in the sample code shown in Listing 2 that I use the 960 Grid framework because it makes my job easy. You also include the feed.php code you just wrote and then process the $venues_array array so that it fits into a data table.

The complicated bit is that the Foursquare API is hierarchical, with the first level (groups) being pretty meaningless to you. What you need is access to the venues level because that's where you're going to loop through and pull out valuable information for later use.

Part of the example shown in Listing 2 provides you with a bit of shorthand that does that: foreach ($venues_array->groups[0]->venues as $v){ starts the loop at the right place in the PHP data object and allows you to access items like $v->name for venue name and $v->stats->herenow for the number of check-ins currently at the venue.

In fact, if you visualize the data structure of $v each time through the loop, it looks a bit like Listing 2.

Listing 2. PHP data object for each venue
stdClass Object
    [id] => 5261
    [name] => Driskill Hotel
    [primarycategory] => stdClass Object
            [id] => 79273
            [fullpathname] => Travel:Hotel
            [nodename] => Hotel
            [iconurl] =>

    [address] => 604 Brazos St
    [crossstreet] => at W 6th St
    [city] => Austin
    [state] => TX
    [zip] => 78701
    [geolat] => 30.2679601
    [geolong] => -97.7413707
    [stats] => stdClass Object
            [herenow] => 0
    [phone] => 5124745911
    [distance] => 0

The code snippet in Listing 3 provides the entire index.php page, complete with a loop through the data structure, pulling out the relevant bits to a $final array, which is then used to create a data table. The result is a dashboard that shows the name of the venue, its address and phone number, and how many people are checked in there.

Also, please note that because phone number is not a required field for a venue, you have to run a quick check to see if it's been included in the data feed. If so, print the number; if not, omit it.

Listing 3. Building the index.php view
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
<html xmlns="" xml:lang="en">
    <meta http-equiv="Content-Type" content="text/html;charset=UTF-8" />
    <title>FourSquare API Test</title>
    <link rel="stylesheet" type="text/css" href="css/960.css" media="all" />
    <link rel="stylesheet" type="text/css" href="css/reset.css" media="all" />
    <link rel="stylesheet" type="text/css" href="css/text.css" media="all" />
    <link rel="stylesheet" type="text/css" href="css/tables.css" media="all" />

	 <div class="container_12">
	 	<div class="grid_12">
	 	<h1>FourSquare API Test</h1>

	 <div class="container_12">
	 	<div class="grid_12" id="updates">
		include_once 'feed.php'; 
	 	$final = array();
	 	foreach ($venues_array->groups[0]->venues as $v){
	 		if (isset($v->phone)){
	 			$PHONE = $v->phone;
	 			$PHONE = "not listed";
	 		$final[$v->id] = array(
	 						'name' => $v->name, 
	 						'address' => $v->address, 
	 						'herenow' => $v->stats->herenow,
	 						'phone' => $PHONE
	 	<table border='1' cellspacing='0' cellpadding='0'>
	 		<tr valign='top'>
	 		<th>Here Now</th>
	 	foreach ($final as $key => $data){
	 		echo "<tr valign='top'>";
	 		echo "<td>".$data['name']."</td>\n";
	 		echo "<td>". $data['address']."</td>\n";
	 		echo "<td>". $data['phone']."</td>\n";
	 		echo "<td align='center'>". $data['herenow']."</td>\n";
	 		echo "</tr>\n";

Most of the code example beyond the PHP is just to make it look good for people and isn't necessarily functional. You can apply your own styles and approaches to make the information visually coherent. For example, you can tie the JSON feed from the PHP file into a jQuery.getJSON() method so it can be refreshed without having to refresh the Web page.

You can also use a simpler, straightforward list to present the information so that it appears more natural within the context of a narrow smartphone screen. For example, Listing 4 shows the final foreach loop, generating a list.

Listing 4. Simplified listing
	 	foreach ($final as $key => $data){
	 		echo "<li>";
	 		echo $data['name']." (". $data['herenow'].")". "<br/>\n";
	 		echo $data['address']."<br/>\n";
	 		echo $data['phone']."<br/>\n";
	 		echo "</li>\n";

Simply adding a few classes to the UL and LI nodes creates a compelling visual experience for anyone on an iPhone or other mobile device. They can check your web page, see what's happening at the locations around the specific geolat/geolong coordinates, and be able to decide where to go for the evening.

What else can you do to improve the users' experience? Require a user to authenticate on Foursquare to see more detail. The details about how to do this are beyond the scope of this article, but when users are authenticated, you can deliver even more information about their specific friends on this list. You can also provide a simple map interface to allow users to choose a geolat/geolong coordinate to begin with, making this a more generally useful tool.


Now that you know how to use the Foursquare API, it's your turn to create something interesting. Before you go too deep, though, check out what others are doing with the API. Foursquare's App Gallery contains some notable applications that others have created (see Related topics).

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

Zone=Open source
ArticleTitle=Introduction to the Foursquare API