The content on our Facebook Page – http://facebook.com/giglondon – is fully automated, from creating daily events to posting updates of the best gigs each month. The first obstacle that we face in connecting with Facebook is that we need an API Key/Secret and a Session Key.

Facebook API Key/Secret and Session Key

• For the API Key and Secret, go to http://www.facebook.com/developers and click on the ‘Set Up New Application’ button, which gives you a unique API Key and Secret for your application.
• To get a Session Key, do the following:
1. Copy & paste the following URL into a browser, remembering to replace <API Key> with your unique API Key:
   http://www.facebook.com/login.php?api_key=<API Key>&connect_display=popup&v=1.0&next=http://www.facebook.com/connect/login_success.html&cancel_url=http://www.facebook.com/connect/login_failure.html&fbconnect=true&return_session=true&session_key_only=true&req_perms=create_event,publish_stream,offline_access
2. Login with the Facebook account that is an Admin user of your Facebook Page (important!).
3. Click on ‘Allow’ until you get to the Success page, whereby the redirect URL will be something like:
   http://www.facebook.com/connect/login_success.html?session={”session_key”:<Session Key>,”uid”:<User Id>,”expires”:0,”secret”:<Session Secret>,”sig”:<Signature>}
4. Copy the <Session Key> and <User Id> values from that URL and keep them safe.

If you have any difficulty with what’s been outlined above, I encourage you to look at this great blog, which will take you step by step through how to generate the Facebook API Key/Secret and Session Key.

Facebook Java API

The Facebook Java API is a Facebook client that can be used to push content over to a Facebook Page.

The easiest option is to include the client library as a dependency in your Maven pom.xml file. If Maven isn’t your preferred option, download the library from here.

<dependency>
  <groupId>com.google.code.facebookapi</groupId>
  <artifactId>facebook-java-api</artifactId>
  <version>3.0.2</version>
</dependency>

Posting Your First Facebook Page Update

...
import com.google.code.facebookapi.*;
...
  // Replace the values with your unique API Key/Secret and Session Key!
  public final static String FACEBOOK_API_KEY = "API KEY";
  public final static String FACEBOOK_API_SECRET = "API SECRET";
  public final static String SESSION_KEY = "SESSION KEY";

  // Replace the User Id with the Admin User Id of the Facebook Page
  public final static String USER_ID = "USER ID";

  // Replace the Facebook Page Id - if you don't know your Facebook Page Id this link
  // will tell you how to find it: http://support.wibiya.com/entries/187061-how-to-find-your-facebook-fan-page-id
  public final static String FACEBOOK_PAGE_ID = "FACEBOOK PAGE ID";

  public void myFirstPost() throws Exception {
    // First we create the client with the API Key/Secret and Session Key
    FacebookJsonRestClient client = new FacebookJsonRestClient(FACEBOOK_API_KEY, FACEBOOK_API_SECRET, SESSION_KEY);

    // Image attachment to make our first post more eye catching (note: you can add as many images as you like)
    Attachment attachment = new Attachment();
    // The first URL is the image URL, the second is the URL that the user is taken to when they click the image
    attachment.addMedia(
      new AttachmentMediaImage(
        "http://blog.niteviva.com/wp-content/uploads/2010/06/cool.jpg",
        "http://blog.niteviva.com/wp-content/uploads/2010/06/cool.jpg"));

    // Post your first post!
    client.stream_publish(
      "Snoopy is too cool for school",
      attachment, null, new Long(FACEBOOK_PAGE_ID), new Long(USER_ID));
  }

If all goes well then you will see the post on the wall of your Facebook Page .. sweet!

Facebook Page Events

We can do so much more with the Facebook API .. here’s a code snippet on creating an event:

  public void newEvent() throws Exception {
    FacebookJsonRestClient client = new FacebookJsonRestClient(FACEBOOK_API_KEY, FACEBOOK_API_SECRET, SESSION_KEY);

    // Convert the event date/time to seconds
    Date eventDateTime = new SimpleDateFormat("yyyy-MM-dd HH:mm").parse("2010-12-25 21:00");
    String eventTimeInSeconds = new Long(eventDateTime.getTime() / 1000).toString();

    // Create event info map
    Map<String, String> event = new HashMap<String, String>();
    event.put("start_time", eventTimeInSeconds);
    event.put("name", "Snoopy & Friends Xmas Party");
    event.put("location", "Charlie Brown's Crib");
    event.put("page_id", FACEBOOK_PAGE_ID);
    event.put("privacy_type", "OPEN");
    event.put("description", "FYI Snoopy loves root beer and pizza!");

    // Post new event
    client.events_create(event);
  }

Sadly the Facebook Java API client library doesn’t (at the time of writing) support adding images to events out of the box. The only option is to extend the client library code, which we’ve managed to do successfully. Please leave a comment below if you want more information on that specific issue.

That’s all folks .. and whatever you do, don’t forget to like our Facebook Page – http://facebook.com/giglondon

This has been implemented on our live environment, so for a real live demo go to http://niteviva.com and sign in using your Foursquare account. Note that, for account verification and security reasons, you will be asked for your email address when you sign up. You will then be taken to the home page where your Foursquare check-in feed will be displayed on the top right-hand corner.

Foursquare’s API has various client libraries that we can use to start developing with the API. Here, foursquared has been chosen because Java is what we find easy to work with when using third-party APIs. You will need to be comfortable working with Java and Maven to complete the following steps, but even if Java isn’t your cup of tea, this post is still useful to those of you who are generally interested in getting started with Foursquare’s API. Case in point, some of what’s said in this post is based on a great blog post by Joe Siewert, which shows how to get started with Foursquare and PHP.

Step 1. Download and install the Foursquare client library

1. Download it here or from foursquared
2. Install the jar in your local Maven repository, e.g.:

mvn install:install-file -Dfile=~/Downloads/foursquarelib_2009111500.jar -DgeneratePom=true
-DgroupId=com.joelapenna.foursquare -DartifactId=foursquare -Dversion=2009111500 -Dpackaging=jar

3. Include the following dependencies in your pom.xml:

   <dependency>
     <groupId>com.joelapenna.foursquare</groupId>
     <artifactId>foursquare</artifactId>
     <version>2009111500</version>
   </dependency>
   <dependency>
     <groupId>xpp3</groupId>
     <artifactId>xpp3</artifactId>
     <version>1.1.4c</version>
   </dependency>
   <dependency>
     <groupId>oauth.signpost</groupId>
     <artifactId>signpost-core</artifactId>
     <version>1.1</version>
   </dependency>
   <dependency>
     <groupId>oauth.signpost</groupId>
     <artifactId>signpost-commonshttp4</artifactId>
     <version>1.1</version>
   </dependency>

Step 2. Code!

Now you’re ready to start using the Foursquare API .. well, almost! First you need to write some code.

package myapp;

import java.util.ArrayList;
import java.util.List;

import com.joelapenna.foursquare.Foursquare;
import com.joelapenna.foursquare.FoursquareHttpApiV1;
import com.joelapenna.foursquare.Foursquare.Location;
import com.joelapenna.foursquare.types.Group;
import com.joelapenna.foursquare.types.Venue;

/**
 * NoAuthFoursquareService uses Foursquare client to make non authenticated Foursquare calls.
 */
public class NoAuthFoursquareService {

	/** The no auth foursquare. */
	protected final Foursquare noAuthFoursquare;

	/**
	 * Instantiates a new non authenticated foursquare service.
	 */
	public NoAuthFoursquareService() {
	  this.noAuthFoursquare = new Foursquare(new FoursquareHttpApiV1("api.foursquare.com", null, false));
	  noAuthFoursquare.setCredentials("", "");
	}

  	/**
	 * Venues.
	 *
	 * @param latitude the latitude
	 * @param longitude the longitude
	 * @return the group
	 */
	public List<Venue> venues(String latitude, String longitude) throws Exception {

	    // Make Foursquare venues API call
	    Group<Group<Venue>> venues =
	      this.noAuthFoursquare.venues(new Location(latitude, longitude), "", 1, 10);

	    // Convert venues into list
	    List<Venue> venueList = new ArrayList<Venue>();
	    for(Group<Venue> venueGroup: venues) {
	      for(Venue venue: venueGroup) {
	        venueList.add(venue);
	      }
	    }

	    return venueList;
	}
}

Step 3. Take it for a test spin

package myapp;

import static org.junit.Assert.assertEquals;
import java.util.List;
import org.junit.Test;

import com.joelapenna.foursquare.types.Venue;

/**
 * Testing non authenticated Foursquare API calls
 */
public class NoAuthFoursquareTest {

  /** The non authenticated foursquare service that's going to be tested. */
  NoAuthFoursquareService noAuthFoursquareService = new NoAuthFoursquareService();

  /**
   * Test call to Foursquare venues API
   *
   * @throws Exception the exception
   */
  @Test
  public void venues() throws Exception {
    List<Venue> venues = noAuthFoursquareService.venues("51.5517", "-0.158826");

    assertEquals(10, venues.size());
    for (Venue venue: venues) {
      System.out.println(
          venue.getName() + ", " + venue.getAddress() + ", " + venue.getCity()
          + " [lat:" + venue.getGeolat() + ", long:" + venue.getGeolong() + "]");
    }
  }
}

If all goes well, you should see some test output:

1st floor chocolate machine, Mediacom, Camden [lat:51.5517059, long:-0.1588255]
Camden rock, Camden, London [lat:51.5517059, long:-0.1588255]
Centro Cafe, Camden, London [lat:51.5517059, long:-0.1588255]
Muang thai, Camden, London [lat:51.5517059, long:-0.1588255]
Somerfield, Camden, London [lat:51.5517059, long:-0.1588255]
the ice wharf, Camden, London [lat:51.5517059, long:-0.1588255]
Palushi's barber, Southampton Road, Camden Town [lat:51.55153896107019, long:-0.15754222869873047]
Lord Weetch's Manor, 9a Parkhill Rd, Camden Town [lat:51.550125, long:-0.1585858]
The IDM, 1 Park Road, London [lat:51.5504938, long:-0.1601123]
The Lord Stanley, 51 camden park road, London [lat:51.5516975, long:-0.1605962]


Step 4. Realtime Geolocation Check-in Feeds

Here it get’s that little bit more tricky. We need the user to authorize our application so we can get access to their realtime check-ins. From now onwards, it helps to understand how OAuth works.

First, you need an application key and secret from Foursquare. Create a Foursquare test account and go to http://foursquare.com/oauth. Register a new consumer with the callback URL ‘http://localhost:8080/foursquare/oauth’, and then Foursquare will give you a unique consumer key and secret.

Now, some more code

package myapp;

import oauth.signpost.OAuthProvider;
import oauth.signpost.basic.DefaultOAuthProvider;
import oauth.signpost.commonshttp.CommonsHttpOAuthConsumer;
import oauth.signpost.signature.SignatureMethod;

import java.util.List;

import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.DefaultHttpClient;

import com.joelapenna.foursquare.Foursquare;
import com.joelapenna.foursquare.FoursquareHttpApiV1;
import com.joelapenna.foursquare.http.AbstractHttpApi;
import com.joelapenna.foursquare.http.HttpApiWithOAuth;
import com.joelapenna.foursquare.parsers.CheckinParser;
import com.joelapenna.foursquare.parsers.GroupParser;
import com.joelapenna.foursquare.parsers.UserParser;
import com.joelapenna.foursquare.types.Checkin;
import com.joelapenna.foursquare.types.Group;
import com.joelapenna.foursquare.types.User;

/**
 * FoursquareService uses Foursquare client to make authenticated Foursquare API calls.
 */
public class OAuthFoursquareService {

	/** The Constant URL_API. */
	private static final String URL_API = "http://api.foursquare.com/v1";

	/** The Constant URL_API_USER. */
	private static final String URL_API_USER = URL_API + "/user";

	/** The Constant URL_API_HISTORY. */
	private static final String URL_API_HISTORY = URL_API + "/history";

	/** The http client. */
	protected final DefaultHttpClient mHttpClient = AbstractHttpApi.createHttpClient();

	/** The consumer key. */
	protected final String consumerKey;

	/** The consumer secret. */
	protected final String consumerSecret;

	/**
	 * Instantiates a new OAuth foursquare service.
	 */
	public OAuthFoursquareService(String consumerKey, String consumerSecret) {
	  this.consumerKey = consumerKey;
	  this.consumerSecret = consumerSecret;
	}

	/**
	 * New foursquare OAuth provider.
	 *
	 * @return the OAuth provider
	 */
	public OAuthProvider newOAuthProvider() {
	  OAuthProvider provider = new DefaultOAuthProvider(
	      new CommonsHttpOAuthConsumer(consumerKey, consumerSecret, SignatureMethod.HMAC_SHA1),
        "http://foursquare.com/oauth/request_token",
        "http://foursquare.com/oauth/access_token",
        "http://foursquare.com/oauth/authorize");
	  return provider;
	}

	/**
	 * Gets the user.
	 *
	 * @param token the token
	 * @param secret the secret
	 * @return the user
	 */
	public User getUser(String token, String secret) throws Exception {
	  HttpApiWithOAuth mHttpApi = new HttpApiWithOAuth(mHttpClient, null);
	  mHttpApi.setOAuthConsumerCredentials(consumerKey, consumerSecret);
	  mHttpApi.setOAuthTokenWithSecret(token, secret);
	  HttpGet httpGet = mHttpApi.createHttpGet(URL_API_USER);
	  return (User) mHttpApi.doHttpRequest(httpGet, new UserParser());
	}

	/**
	 * Checkin History.
	 *
	 * @param token the token
	 * @param secret the secret
	 * @return the group
	 */
	@SuppressWarnings("unchecked")
  	public List<Checkin> history(String token, String secret) throws Exception {
  	  HttpApiWithOAuth mHttpApi = new HttpApiWithOAuth(mHttpClient, null);
      mHttpApi.setOAuthConsumerCredentials(consumerKey, consumerSecret);
      mHttpApi.setOAuthTokenWithSecret(token, secret);
      HttpGet httpGet = mHttpApi.createHttpGet(URL_API_HISTORY);
      Group<Checkin> checkinGroup = (Group<Checkin>) mHttpApi.doHttpRequest(httpGet, new GroupParser(new CheckinParser()));
      return checkinGroup.subList(0, checkinGroup.size());
	}

	/**
	 * New OAuth client.
	 *
	 * @param token the token
	 * @param secret the secret
	 * @return the foursquare
	 */
	protected Foursquare newOAuthClient(String token, String secret) {
	  Foursquare foursquareOAuthClient =
	    new Foursquare(new FoursquareHttpApiV1("api.foursquare.com", null, true));
	  foursquareOAuthClient.setOAuthConsumerCredentials(consumerKey, consumerSecret);
	  foursquareOAuthClient.setOAuthToken(token, secret);
	  return foursquareOAuthClient;
	}

}

To start using the OAuthFoursquareService, you have to hook it up into the web layer. I’m not going to go in depth at this stage, but here’s a code example of how it can be done using a Spring MVC controller:

package myapp;

import oauth.signpost.OAuthProvider;
import com.joelapenna.foursquare.types.Checkin;
import com.joelapenna.foursquare.types.User;

import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

import javax.servlet.http.HttpSession;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.servlet.View;
import org.springframework.web.servlet.ModelAndView;
import org.springframework.web.servlet.view.RedirectView;

/**
 * FoursquareController handles oauth requests (authorize and oauth callback)
 */
@Controller
@RequestMapping("/foursquare")
public class FoursquareController {

	/** The foursquare service. */
	@Autowired
	public OAuthFoursquareService foursquareService;

	/** The Constant accessTokens that stores OAuth access tokens */
	public static final Map<String, String[]> accessTokens = new ConcurrentHashMap<String, String[]>();

	/**
	 * Authorize - redirects user to a foursquare authorization url
	 *
	 * @param returnUrl the return url
	 * @throws Exception the exception
	 */
	@RequestMapping(value = "/authorize", method = RequestMethod.GET)
	public View authorize(HttpSession session) throws Exception {

	  // Get authorize url, save OAuthProvider into HTTP session (retrieved in oauth callback method)
	  OAuthProvider provider = foursquareService.newOAuthProvider();
	  String authorizeUrl = provider.retrieveRequestToken("http://localhost:8080/foursquare/oauth");
	  session.setAttribute("foursquare", provider);

	  return new RedirectView(authorizeUrl);
	}

	/**
	 * OAuth Callback.
	 *
	 * @param oauthToken the oauth token
	 * @throws Exception the exception
	 */
	@RequestMapping(value = "/oauth", method = RequestMethod.GET)
  	public View oauth(
  		HttpSession session, @RequestParam("oauth_token") String oauthToken) throws Exception {

	  // Get OAuthProvider from HTTP session (set in authorize method), and get access token and secret
	  OAuthProvider provider = (OAuthProvider) session.getAttribute("foursquare");
	  provider.retrieveAccessToken("http://localhost:8080/foursquare/oauth");
	  String token = provider.getConsumer().getToken();
	  String tokenSecret = provider.getConsumer().getTokenSecret();	  

	  // Get user info from foursquare API
	  User user = foursquareService.getUser(token, tokenSecret);

	  // NOTE: Put access token and secret in accessToken map, which is fine for this example but
	  // normally the access token and secret would be stored in a database!
	  accessTokens.put(user.getId(), new String[]{token, tokenSecret});	  

	  return RedirectView("http://localhost:8080/foursquare/checkins/" + user.getId());
	}

	/**
	 * Checkins.
	 *
	 * @param userId the user id
	 * @return the model and view
	 * @throws Exception the exception
	 */
	@RequestMapping(value = "/checkins/{id}", method = RequestMethod.GET)
  	public ModelAndView checkins(@PathVariable String id) throws Exception {
	  String[] accessToken = accessTokens.get(id);

	  if (null == accessToken)
	    throw new Exception("Foursquare user not yet authenticated [" + id + "]");

	  // Get user check-ins from foursquare API
	  List<Checkin> checkins = foursquareService.history(accessToken[0], accessToken[1]);

	  Map<String, List<Checkin>> model = new HashMap<String, List<Checkin>>();
      model.put("checkins", checkins);
	  return new ModelAndView("checkins", model);
	}

}

The above web flow works as follows:

1. The user clicks on a HTML link that directs them to http://localhost:8080/foursquare/authorize
2. The user is redirected to the Foursquare website, which asks the user to authorize our application so we can access their Foursquare realtime check-in feed
3. The user is taken back to http://localhost:8080/foursquare/oauth, which accepts and stores the new access token for that user
4. The user is finally redirected to http://localhost:8080/foursquare/checkins/{id}, which calls the Foursquare API to get the user’s realtime check-in feed

Hope this post has been useful in explaining how you can get started with Foursquare’s API.
If you have any questions or feedback, please leave a comment.

Don’t forget you can try out a real live demo at http://niteviva.com .. enjoy

One quick solution was to open *.ftl with the WTP HTML editor, to do that right click on an ftl file and select ‘open with…’ and follow the prompts. The only problem is that Eclipse then started showing errors on a lot of the templates so we had to disable validation . To do the same, open Eclipse preferences and find the Web/Html file/validation page screen and set all of the values set to  ’Error’ to ‘Warning’ or ‘Ignore’.

A quick refresh and rebuild removes all of those pesky build error markers

First of all I started moving the sub-projects over to Maven, it may not be the most popular build system right now, but nothing comes close to Maven for Java development right now. Once the project hierarchies were in place I had to put a private repository in place so we could share libraries and plugins. I spent a few hours looking at repository managers at this point, but we’ve decided to go without one for now. I know from experience that this will become an issue later when we want to install additional libraries that don’t exist in public repositories, think javax-*, but with a small team of developers we can afford to skip it for now.

I thought about setting up the deployments to use Webdav, I’d used that at one of my old client’s sites and it worked pretty well, but seeing as we already have an SSH key setup in place, including extensive use of ~/.ssh/config files, using SSH & SCP was quicker and easier. One little trick I picked up this time around was to change the addresses for deployments from scp://… to scpexe:// so the system scp application is used rather than the Maven wagon so our URLs can use our SSH aliases.

Next up, we needed a CI server so don’t have to run the live builds from our laptops anymore! I’ve tried quite a few CI servers over the years, but I think Hudson has stabilised a lot over the last couple of years so I’ve decided to drop it in here too. I have a few issues with Hudson’s UI, I’ve seen installations with 300+ jobs and it becomes difficult to find anything without a grouping scheme (I don’t think views cut it), and it takes too long to navigate to some features, but on the whole it is a great little tool.

The two main differences between the build system we have now and the ones I’ve used before are;

1. Authentication, some have used VPN and left the services open internally whilst others have made extensive use of x509 certificates, here I’ve set up SSH keys to authenticate developers.
2. We’re using Git for SCM so you need to figure out your repository layout up-front. I’ll probably write another post about our choice of Git over the incumbent open source SCM, but the combination of Git and Github has worked really well for us and fits into our SSH key setup nicely.

All in, it only took a few hours to get everything up and running. I wasted part of that looking at repository managers before realising that we just don’t need one yet. The rest is all standard issue, but it does impress me how Maven and Hudson have grown up since I used them first, Maven especially, it was a terrible toddler but it has really grown up over the last year.

I’ve taken inspiration from an awesome jquery plugin from coda and developed some jquery code that goes and fetches realtime twitter reactions.

To begin, download the source and include the following scripts in your page:

<script type="text/javascript" src="js/jquery-1.3.2.js"></script>
<script type="text/javascript" src="js/jquery.page-realtime-twitter-reactions.js"></script>

Next, add a “page-realtime-reactions” div element to your page, wherever you want the realtime reactions to appear:

<div id="page-realtime-reactions"></div>

Finally, add the following jquery code, changing the query parameter to suit your needs:

<script type="text/javascript">
  $(document).ready(function() {
    $("#page-realtime-reactions").getPageRealtimeReactions({
    query: "Realtime Twitter Reactions using JQuery OR http://blog.niteviva.com/development/realtime-twitter-reactions-using-jquery OR http://tinyurl.com/yfahkgd",
    numTweets: 5,
    loaderText: "Loading ...",
    slideIn: true,
    showHeading: false
    });
  });
</script>

Hope you enjoy playing with this neat little plugin, and why not tweet about it (comments are so 1990!), and be amazed when you see your tweet appear above