Tutorial: Recommended Venues

Here's a step by step guide on how we built the recommended venues sample. Feel free to use the code and ideas as inspiration. This sample uses the JavaScript OAuth flow.

  1. The first step is registering an OAuth consumer. Go to Your Apps and click the "Create A New App" button. Fill in the Application Name, Application Website, and Redirect URI fields. The Redirect URI is the URL that user will be returned to after authorizing your application on foursquare. In this case, both the Application Website and Redirect URI are:

    https://developer.foursquare.com/docs/samples/explore

    Registering a consumer will give you API credentials. The Client ID and Client Secret are unique to your consumer. Make sure you keep your Client Secret, uh, secret.

  2. We're going to start with some basic code. All I've done is set up the HTML structure of the page. For this example, I will use JQuery, JQuery BBQ, Leaflet and the MapBox API. You can find the referenced apisamples JavaScript and CSS files online.

  3. The next step is authenticating the user. The venues/explore endpoint does not require an acting user, but if the request is made on behalf of a user, the recommendations are personalized for that user. I'm using JQuery BBQ to parse the URL for the access token, but you could skip this library and parse:

    window.location.hash

  4. Now that we have an access token for the user, we're going to use the HTML5 geolocation API to determine the user's location. We're then going to create a map using Leaflet and the MapBox API that is centered on the user's location. Note: Make a custom map and get your own API URL at MapBox.com/foursquare

  5. The final step is querying the foursquare API for recommended venues and placing a marker on the map for each venue. The venues/explore endpoint responds to GET requests so you can attach parameters to the URL. In this case, we're sending the user's latitude and longitude via the ll parameter. You must include the access token when making an authenticated request. We'll also label each marker with its category icon from the foursquare API and use CSS to add a background image to frame them.

  6. That's it!