Mr. Jitters for iOS

We believe that the Foursquare API is the most advanced location API in the world, used by independent developers and global enterprises alike. As app developers ourselves, we wanted to show how simple it can be to incorporate powerful location intelligence into an app.

To highlight a few location endpoints common in many applications, we created a sample app called Mr. Jitters. Mr. Jitters for iOS is available on the App Store and also open sourced on GitHub.

We love coffee, so we decided to bring to mobile the beloved Mr. Jitters sticker from Swarm as a way to quickly find the best coffee around, wherever you are in the world. We wanted to take this very simple concept of finding coffee and show off two Foursquare API endpoints in the process: search and explore.

Overview

After opening the app, users can start their quest to get caffeinated by tapping on the Mr. Jitters icon in the middle of the screen. We then present the user with the venue they’re currently at, as well as the best coffee shops within walking distance. If a user taps on a row they see the coffee shop on a map where they can get directions or more information from Foursquare.com.

*From left to right: Home screen, search view, map and directions

In this walkthrough you will learn how to:

1. Sign-up for a Foursquare API key
2. Determine where a device is in the real world
3. Find the top recommended venues in an area

If you want to take a look at the live app before continuing you can download it from the App Store.

This tutorial is written in Swift 3 and is intended for those who are familiar with iOS development. If you’ve never built an iOS app before, check out some of the great online resources to get you started.

Get the code

The best way to start is to grab the code from GitHub and open in XCode. The project is built in Swift 3 so you’ll need XCode 8 or higher.

App structure

The app is made up of three View Controllers:

1. HomeController.swift | Home screen with coffee search button
2. SearchController.swift | Search results page that displays the current venue you’re at and the best coffee nearby
3. DetailsController.swift | Displays the coffee shop in a map view with a link to the Foursquare venue page and a link for directions

For simplicity sake, we decided to not use third party libraries for Core Location or HTTP networking. This way, you should be able to copy-paste any of this code into your own apps without having to install additional dependencies. However if your app is already using libraries like Alamofire or SwiftLocation you should be able to easily integrate this code into those packages.

Setting up Foursquare API

To sign-up for a free Foursquare API key navigate to developer.foursquare.com and create a new app. After you create a new app you’ll get two very important pieces of information, a client id and client secret. You’ll need both of these to start making API calls to Foursquare.

Once you get your client id and client secret, paste them into the CLIENT_ID and CLIENT_SECRET variables in SearchController.swift

let client_id = “CLIENT_ID” 
let client_secret = “CLIENT_SECRET”

Build and run the app

At this point you should be able to build and run the app. Tap the Mr. Jitters icon and you’ll be presented with the best coffee shops nearby, as well as the venue you’re currently at. You should be able to tap on a coffee shop to see it on a map, get directions or view on Foursquare.

Foursquare API methods

Now that you’ve got your app up and running, lets look into some of the code where the Foursquare API endpoints are used. The SearchController.swift file is where we do all of our networking with Foursquare API.

Determine where a device is in the real world

In SearchController.swift, we call the snapToPlace() function to determine what venue the device is currently at. The most important thing to look at in this function is how we set up the for the venues/search endpoint.

let url = “https://api.foursquare.com/v2/venues/search?ll=\(currentLocation.latitude),\(currentLocation.longitude)&v=20160607&intent=checkin&limit=1&radius=4000&client_id=\(client_id)&client_secret=\(client_secret)"

Typically, this endpoint is used to search for a specific venue, but it works really well in the other direction to0 — determining what venue is at a latitude/longitude.

Accomplishing this is very simple, all you really need to include is a ll parameter where we pass in the latitude and longitude of the device’s current location. In this case we also are setting limit=1 since we only need the first venue, there’s no point in wasting bandwidth returning additional venues. We also set radius=4000 since there’s no point of returning a venue that’s far away if we’re in a rural area.

With any API call to Foursquare, you need to include authentication and a version. We authenticate with the client_id and client_secret parameters, passing the values we got when we setup our API key. We tell the API what version to use with the v parameter. You can read more about versioning here, but in general v will equal the date that you’ve built and tested your app.

After our URL is constructed, you can make a GET request in your preferred method, using URLSession as we did here or via a library such as Alamofire. Once we retrieve a response from Foursquare, we used SwiftyJSON to parse the response into the currentLocationLabel.

Find the top recommended venues in an area

While the snapToPlace() function is talking to Foursquare asynchronously, we are making another call in the searchForCoffee function to get the best coffee shops nearby. Here we use the search/recommendations endpoint, let’s look at how this URL is constructed.

let url = “https://api.foursquare.com/v2/search/recommendations?ll=\(currentLocation.latitude),\(currentLocation.longitude)&v=20160607&intent=coffee&limit=15&client_id=\(client_id)&client_secret=\(client_secret)"

Similarly to the venues/search call we made in the snapToPlace() function, we send a ll parameter with the devices current location, our client_id and client_secret, and the v parameter for versioning.

Here we are also including an intent parameter. This parameter is used to set the top-level intent of the search and can be: food, breakfast, brunch, lunch, coffee, dinner, dessert, drinks, shopping, fun, or sights. In this case we set the limit=15 because we’d like to see the top 15 coffee shops nearby.

Now that you have this URL, you can make a GET request as you did previously. We again use SwiftyJSON to parse this response into the searchResults array that populates our table view.

Recap

We wanted to show how simple it can be to incorporate powerful location intelligence into an app. In this walkthrough you learned the basics of how to retrieve venues via the Foursquare API.

1. You can sign up for an API key at developer.foursquare.com. You’ll need this key before you can start making API requests to Foursquare.
2. You can use the venues/search endpoint to determine where a device is in the real world. This endpoint can be used to search for a specific venue, or in our case it’s used to determine what venue is at a given latitude/longitude by including only a ll parameter and setting the limit to 1.
3. The search/recommendations endpoint can be used to find the best (or recommended) venues in an area. This endpoint can take different intents such as: food, coffee, dessert, drinks, etc. Or you can use a query parameter for more specific tastes.

I encourage you to dive into the Foursquare API even more. Now that you’ve gotten the basics, check out the rest of our endpoints here: developer.foursquare.com/docs. And don’t forget to include the Foursquare stamp of approval to your app. We can’t wait to see the great things that you’ll build with Foursquare.