After 550 check-ins to date, primarily via SMS, I have a wish list of enhancements that would make Foursquare via SMS so much easier to use.

First a little background.  I’m a huge fan of the service and want it to succeed, but the SMS experience is frustrating at best.  The biggest problem is getting the SMS check-in to link up with the corresponding Foursquare venue.  I know I’m not alone as I see similar problems reported on the Get Satisfaction support site and a Twitter search turned up some frustrated comments as well.

I realize SMS users probably make up a tiny percentage of the overall Foursquare user base.  I know the apps for the iPhone and Android devices provide a much better experience.  But at its core, Foursquare is about sharing your location with friends and I think this functionality is achievable with any mobile device.

SMS is like the mobile equivalent of the command line on the PC.  Ultimately a simple yet extremely powerful way of interacting with computer systems.  Fred Wilson wrote about the importance of SMS last summer, calling it the least common denominator for mobile apps.

I think it is critical, particularly early on in the commercialization of a mobile web service, for there to be an easy and quick SMS interface.

For your consideration, here is my wish list:

• Allow user to change location via SMS.  If you are traveling to different cities (even suburbs) and the venue you want to check-in to doesn’t match your current city, the check-in fails.
  • Could be as simple as texting your city or zip:  “in Minneapolis, MN” or “in 55415″
• If a check-in isn’t recognized, send back a list of close venue matches.  If I see the right venue, let me text back the number from the list and check me in there instead.
• If I don’t see the venue I want in the results, post my raw check-in anyway (it does this today), but then on the history page let me go back later and link my raw check-in to the correct venue.
• Better SMS documentation would help tremendously.  SMS users have pieced a lot together through trial and error, but it would be great to know how some things are working in the background.
  • For example, I’ve heard there are aliases for venues and I have seen old venue names work from time to time, but it would be helpful to know exactly how this works.

I know there are higher priorities for a fast growing startup with limited resources, but I think a great SMS experience is an important component of the product and it can help grow and maintain the Foursquare user base.  If there is any way I can help improve the SMS experience let me know.

If you are a Foursquare user that shares these frustrations leave a comment here or on the corresponding post on Get Satisfaction.

Events like this are a great way for restaurants and bars to generate business and connect with customers.  Pazzaluna, also in St. Paul, did a similar event a few months ago and AJ Bombers of Milwaukee is one of the best success examples I have seen so far.  If you know of other events like this in the Twin Cities let me know.

• Foursquare API documentation
• Foursquare OAuth authentication

Setup your environment

Here is what you’ll need to complete this tutorial:

• Your favorite text editor and web browser
• A web server with PHP (if you need to set one up quick, see my XAMPP tutorial)
• The foursquare-asyc library
• My two example files (you can either download these or create them as we go)
• If you don’t have one already, create a Foursquare account
• A bunch of patience. This stuff can be frustrating.

To begin, setup a project folder on your web server with the necessary files for this example.

Create a folder called “test” and create files inside that folder called index.php and callback.php. Then download the foursquare-async library (click “Download Source” in the upper right corner). Extract the files EpiCurl.php, EpiFoursquare.php and EpiOAuth.php to the test folder.

You now should have a folder called test that is accessible via a browser that contains these files:

• index.php
• callback.php
• EpiCurl.php
• EpiFoursquare.php
• EpiOAuth.php

Note: Depending on your server configuration you may need to manually enable cURL support. I did this example using XAMPP and needed to turn it on. In the php.ini file (C:\xampp\php\php.ini) uncomment the line “extension=php_curl.dll” and then restart Apache. If you get an error like this later in the tutorial it might indicate you need to enable cURL.

Possible cURL error:
Fatal error: Call to undefined function curl_multi_init() in C:\xampp\htdocs\test\EpiCurl.php on line 24

OAuth overview

You can authenticate with Foursquare’s API in one of two ways. The simpler, but less secure way is through basic access authentication. This method requires the user to provide their credentials (username/password) to your application and those credentials get passed right in the web request to the API. It gets the job done, but makes the user’s data more vulnerable. The user is also trusting that the application is storing their credentials securely.

The more secure option we will use in this example is OAuth authentication. OAuth does a better job of protecting the user’s credentials and also gives the user greater control over what applications have access to their account. For example, instead of giving a random application your Foursquare credentials, you instead click on a link within the application that sends you to Foursquare to provide your credentials. Then Foursquare sends you back to the application with appropriate access keys for the application to use. Authenticating this way means that your credentials stay between you and Foursquare. The application you are giving access to only gets the OAuth access keys and doesn’t see or store your actual Foursquare credentials. It sounds complicated, but hopefully this tutorial will clear it up a little. OAuth is becoming more of a standard and as an end user you are probably already authenticating with different applications and web services this way.

Here are the steps for the OAuth workflow that this example will accomplish:

1. Get request key and secret
2. Provide a link to the Foursquare authorization page
3. The user will approve or deny access and be redirected back to your application
4. Get access key and secret (and store in your application database, but we don’t need to for this example)
5. Use access key and secret to make API calls

Register with Foursquare to get your key and secret

The first thing we need to do is register our application with Foursquare to get a request key and secret for our application.  Go to http://foursquare.com/oauth/register, login and fill in the required information.

• Application Name:  OAuth Test
  • Give your application a name (My Foursquare App)
• Application Web Site:  http://localhost/
  • Provide the site where you will host your application (www.mysite.com/my-foursquare-app)
• Callback URL:  http://localhost/test/callback.php
  • This is the URL that Foursquare will send the user to after authenticating (www.mysite.com/my-foursquare-app/callback.php)

Click “Register” and Foursquare should generate a new key and secret for your application.  Your key and secret will be different than mine.

You can always return to http://foursquare.com/oauth/ to change these details or reset your key and secret.  At this point your application is registered and you have a key and secret to use.

Add code to the index.php file

The second task is filling in the index.php file with some code.  Open up index.php and add the following code.  Also if you are curious I am using the SyntaxHighlighter Evolved plug-in for displaying code.

<?php

//Put in the key and secret for your Foursquare app
//Your values will be different than mine
$consumer_key = "XB1NE31CJ4U22EF2GA53C4ULR3SL2BG21G1M5VTRCZ3K1XW5";
$consumer_secret = "3RHRD1KJLGFFHKDMD4SCE11NHNDCFUPOIPOQW4VGKLADFKC1";
$loginurl = "";

//Includes the foursquare-asyc library files
require_once('EpiCurl.php');
require_once('EpiOAuth.php');
require_once('EpiFoursquare.php');

session_start();
try{
  $foursquareObj = new EpiFoursquare($consumer_key, $consumer_secret);
  $results = $foursquareObj->getAuthorizeUrl();
  $loginurl = $results['url'] . "?oauth_token=" . $results['oauth_token'];
  $_SESSION['secret'] = $results['oauth_token_secret'];
} catch (Execption $e) {
  //If there is a problem throw an exception
}

echo "<a href='" . $loginurl . "'>Login Via Foursquare</a>";  //Display the Foursquare login link
echo "<br>";
//This is your OAuth token and secret generated above
//The OAuth token is part of the Foursquare link above
//They are dynamic and will change each time you refresh the page
//If everything is working correctly both of these will show up when you open index.php
var_dump($results['oauth_token']);
echo "<br>";
var_dump($_SESSION['secret']);

?>

Now open index.php in your browser and you should see the following, only your two values will be different.

Add code to the callback.php file

Before you go to the login link you created, we need to add code to the callback.php file.  Now open that one and add this code.

<?php

//Put in the key and secret for your Foursquare app
//Your values will be different than mine
$consumer_key = "XB1NE31CJ4U22EF2GA53C4ULR3SL2BG21G1M5VTRCZ3K1XW5";
$consumer_secret = "3RHRD1KJLGFFHKDMD4SCE11NHNDCFUPOIPOQW4VGKLADFKC1";

//Includes the foursquare-asyc library files
require_once('EpiCurl.php');
require_once('EpiOAuth.php');
require_once('EpiFoursquare.php');

session_start();
$foursquareObj = new EpiFoursquare($consumer_key, $consumer_secret);
$foursquareObj->setToken($_REQUEST['oauth_token'],$_SESSION['secret']);
$token = $foursquareObj->getAccessToken();
$foursquareObj->setToken($token->oauth_token, $token->oauth_token_secret);

try {
   //Making a call to the API
   $foursquareTest = $foursquareObj->get_user();
   print_r($foursquareTest->response);
 } catch (Exception $e) {
   echo "Error: " . $e;
 }

?>

Test it out

Now we are ready to try it all out and make a call to the Foursquare API.  This first call is going to bring back your user information.

Open up index.php in your browser again and click the login link.  This is the part where the user leaves your application and goes to authenticate with Foursquare directly.

Notice that your OAuth token is along for the ride in the URL:

Click on “Allow” and Foursquare will send the user to the callback page you created.

If everything worked correctly you will see your user information in the browser.

Try a few more API calls.  This will call back your check-in history:

//Making a call to the API
$foursquareTest = $foursquareObj->get_history();
print_r($foursquareTest->response);

If you want to make a call with parameters it looks like this.  This will get your user information along with your badges and mayorships:

//Making a call to the API
$params = array("badges"=>1, "mayor"=>1);
$foursquareTest = $foursquareObj->get_user($params);
print_r($foursquareTest->response);

As you look through the API documentation you will notice the different methods described like this:

URL: http://api.foursquare.com/v1/venue
Formats: XML, JSON
HTTP Method(s): GET
Requires Authentication: No, but recommended
Parameters:

• vid – the ID for the venue for which you want information

To call the venue details method above in our example we just need to change a couple things.  We know this method takes in the single parameter vid and we can grab a venue’s ID from its Foursquare URL.  22242 in my example corresponds to the venue Town Talk Diner.  On the next line, combine the HTTP method (GET) with the method name from the URL (venue) to form get_venue.

//Making a call to the API
$params = array("vid"=>22242);
$foursquareTest = $foursquareObj->get_venue($params);
print_r($foursquareTest->response);

Note that every time you go through this process and click “Allow” Foursquare adds another entry for your application.  You can go to your Foursquare settings page to clean these up.  If you were building out an application you would want to save the user’s OAuth information in a database so they don’t have to re-authenticate each time.  For this example the OAuth information is just getting placed in a temporary browser session and thus we have to re-authenticate each time.

Hopefully at this point you are making calls to the API and getting data back.  To go beyond these basic calls refer to the Foursquare API documentation to see everything that is available.  Also refer to the wiki page for the foursquare-asyc library to learn more about how it works.

I’m intrigued by it because it’s simple, visual, social and nicely complements other location/real-time services like Foursquare and Twitter.  Since many locations on Foursquare revolve around food and drink, Eat.ly adds a nice visual context to the great food you find.  Eat.ly nicely integrates with Foursquare and Twitter, so you can update your Eat.ly stream and check-in/tweet at the same time.

There is also a health component to Eat.ly where users can rank how healthy a meal looks.  I’m curious to see where they take this idea.  I think there is an opportunity to provide additional functionality around logging calories, daily food group servings and maybe other metrics from various dieting programs.  It could be a very helpful tool for people who closely track what they eat.

Eat.ly is well positioned to take advantage of a growing trend as well.  The New York Times just ran a piece about a growing number of people who keep photo food diaries.  Unfortunately I didn’t see Eat.ly mentioned in the article.

Eric Friedman, one of the people behind Eat.ly, posted about the project recently and discusses how it’s easier than ever to start a small web project.  He blogs regularly at Marketing.FM.

• Over 500,000 users
• Over 1,000,000 badges have been awarded
• Over 1.4 million venues with 1200 offering specials
• Over 15.5 million checkins

Foursquare has already discussed that checking in is becoming a commodity and this week there was more news about Facebook and Twitter getting into the location game as well.  I even noticed this on my Twitter account today:

Foursquare mentioned that to compete with these threats they need to provide “the most incentive for a user to check-in.” To help reach this goal, this week they announced new analytics tools that will give businesses visibility to information about their Foursquare customers.  Businesses will be able to better understand who is visiting and hopefully use the information to improve on customer retention and acquisition.  As the Foursquare platform evolves and the analytics become more powerful I think we will see interesting promotions to bring in new customers and reward loyal ones.

The analytics tools are an important step to adding more incentive for checking in on Foursquare.  Tools like this should help get some of the 1.4 million (and counting) venues to be active participants on Foursquare.  More businesses using Foursquare and better understanding their customers should lead to innovative promotions (here are some great examples:  AJ Bombers in Milwaukee, Pazzaluna in St. Paul and Starbucks).  Valuable promotions should encourage users to check-in often and help drive new users to Foursquare as well.  Foursquare needs to be the location-based service of choice and tools like this are helping them lead the pack.

Here are some of the partnerships I have seen over the last few weeks.

• Bravo TV
• Zagat
• City of Chicago
• Conde Nast, Marc Jacobs
• And a few more mentioned at TechCrunch and AdAge

As Foursquare continues to grow there is an effort underway to build Foursquare communities by hosting streetup events (basically a meetup with a spin on the name).  Events like this one are popping up all over the place.  Read more about it on the Foursquare streetups page.

The goal with these events is to promote the Foursquare service to both users and businesses by showing how both benefit from using the service.  For businesses, offering Foursquare promotions can help bring in customers and for customers, checking in with Foursquare can redeem promotions, specials, etc.

A small group of us in the Twin Cities plan to continue putting on events like this in the future.  If you run a restaurant or bar and are interested in partnering on hosting an event like this, please contact me.

What Is Foursquare?

Foursquare describes itself as part friend finder, social city guide and nightlife game.  So what does that mean?

Friend Finder

• Users “check-in” to venues from a mobile device.  A venue can be any place people go like a restaurant, bar, museum, park, etc.
• You add friends to your Foursquare account and can then see each other’s check-ins.  Makes meeting up with people on the fly easy!
• Foursquare is integrated with Twitter and Facebook, so you can blast your check-ins out to a broader audience if you want.

Social City Guide

• Each venue on Foursquare has its own profile page that shows all kinds of details about it.
• Users can leave behind short tips at venues telling future users good things to order, try, do, etc.  It’s fun to check these when you visit a place for the first time.
• Venues can create promotions for Foursquare users.  Think freebies and discounts!

Nightlife Game

• Users that check-in at a venue the most often become the Mayor.  Creates an instant incentive for repeat visits.
• Check-ins also earn users points and unlock badges for certain actions.  As Foursquare evolves I think the points will become more meaningful beyond bragging rights.

How Do You Play?

Foursquare is meant to be played from your phone while you’re on the go.  There are Foursquare apps for the iPhone, Android devices, Palm devices and one is on the way for Blackberry too.  Users with phones that don’t have an app can use Foursquare’s mobile page instead (http://foursquare.com/mobile/).  Finally, if you are like me, and don’t have a smartphone, you can still check-in with standard text messages.  The apps provide a more robust user experience, but texting still gets the job done.

To use text messaging send a text to 50500 in this form:

@ Ace Bar ! Playing skeeball

The @ designates the venue name and the ! designates your shout, which is a short message you can include with your check-in.  Note that you need to text in the exact name of the venue for the check-in to register correctly.  You can search venues from Foursquare’s main page to get the exact name.  If the check-in is successful you should get a confirmation message back from Foursquare.

For Businesses

If you’re a local restaurant, bar, etc. you should definitely consider running a promotion on Foursquare.  It’s free to run an offer and can really entice users to stop by.  Find out more and sign-up for promotions here:  http://foursquare.com/businesses/.

For Developers

Foursquare recently opened up an API to developers for building applications to interact with Foursquare.  Developers are already creating some neat software like Mob Zombies.  See more information and examples here:  http://foursquare.com/developers/.

Similar to how Twitter grew in popularity last year and everyone was asking if you tweet, I think this year we’ll see the same thing happen with Foursquare.  If you have any questions about how it works leave a comment below, check Foursquare’s help page or leave a question at their Get Satisfaction site.  Go play!