Mr. Jitters for Android

A sample Android app, powered by Foursquare.

(Looking for a sample app for iOS? Head over to Foursquare API and read our post on Mr. Jitters for iOS.)

At Foursquare, location is at the heart of everything that we do. Through the Foursquare API, we give developers and enterprises opportunities to tap into the core of Foursquare’s location intelligence and empower them to build meaningful experiences and business solutions.

We are extending our love for coffee into an exercise for learning about adapting the Foursquare API on Android. This exercise will go through techniques of requesting data from the Foursquare API, as well as leveraging other libraries/APIs for location and mapping. By the end of this post, you should have a good understanding of how to make requests to the Foursquare API and parse responses from the Foursquare API on Android.

This exercise will touch on two Foursquare API endpoints: venues/search and search/recommendations. To showcase how these API endpoints are used, we developed a sample app, Mr. Jitters. Mr. Jitters is currently available on the Google Play Store, and the sample Android Studio project is available on Github.

In summary, this post will consist of the following sections:

1. Overview
2. What are all of these files?
3. How do I become a Foursquare developer?
4. Foursquare, make me a sandwich!
5. Hello, JSON!
6. Hurray, you did it!

Overview

As a sample app, Mr. Jitters keeps everything simple and highlights the fundamental steps needed to interact with the Foursquare API on Android.

The app contains three basic views — home, location, and map. On the home view, the user begins by tapping on the Mr. Jitter icon. Once on the location view, the user is presented with his/her last-known location and a list of search results. When a coffee spot is selected, a map is shown with the venue’s location marked.

The three views of the Mr. Jitters app — home, location, and map.

Within the three views above, Mr. Jitters does quite a bit of work in the background. When the user taps on the Mr. Jitters icon, the user’s last location is retrieved. Once the user’s location is determined, a request is made to Foursquare to “snap” the user to a known venue. At the same time, another request is made to Foursquare to search for all recommended coffee spots within the immediate area. Finally, when a user clicks on a specific coffee spot, that venue is marked on a map.

In order to interact with different technologies and data sources, Mr. Jitters enlists the help of several libraries. All of the libraries below are imported and compiled via Gradle within Android Studio.

• Google APIs for Android — an API for obtaining user location details
• Retrofit — a client for making HTTP requests
• Gson — a (de)serialization library for converting JSON into Java objects
• Google Maps Android API — an API for displaying custom maps

What are all of these files?

Within the sample Android Studio project, there are 11 Java files, consisting of 3 Activity classes, 1 Adapter class, 1 service interface, and 6 Java Object classes. The model logic is represented by the Java Object classes, and the view/controller logic is represented by the Activity and Adapter classes.

MainActivity— displays the home view and handles the initial user interaction

PlacePickerActivity— calls Google APIs for Android to obtain and display the user’s last-known location, calls the Foursquare API using Retrofit to obtain, and uses Gson to parse the resulting JSON and display a list of search results

MapActivity— displays the map view, plots a marker for a specified venue, and links back to Foursquare

PlacePickerAdapter— handles the view and control of the venue search results for PlacePickerActivity

FoursquareService— provides the Retrofit interface for accessing the Foursquare API with two methods: snapToPlace()and searchCoffee()

FoursquareJSON— represents the JSON returned from the Foursquare API

FoursquareResponse— represents the response object returned within the JSON from the Foursquare API

FoursquareGroup— represents the group object returned within the response object from the Foursquare API

FoursquareResults— represents the results object returned within the group object from the Foursquare API

FoursquareVenue— represents the venue object returned from the Foursquare API (note that the parent of this depends on the type of call)

FoursquareLocation— represents the location object returned within the venue object from the Foursquare API

The Activity and Adapter classes are developed for the Android platform, so we won’t dive into much detail on this topic. The service interface and Java Objects were designed to handle the JSON response from the Foursquare API, and will be further detailed below.

How do I become a Foursquare developer?

To start developing with the Foursquare API, you will need to register for a Foursquare developer app. You can start by visiting the Foursquare for Developers website and creating a new app.

Once you’ve done this, you should have a corresponding client ID and client secret for your app. With a client ID and client secret, you will have access to the Foursquare API endpoints.

For the purposes of this sample project, you will also need to be a Google Maps developer, in order to create and display custom maps. You can get an API key by visiting the Google Maps Android API website.

Now, you can enter these details into the sample project with your API keys. Create a new file called res/values/api.xml with the following contents:

Foursquare, make me a sandwich!

Unfortunately, you can’t send a request for a sandwich to the Foursquare API (sorry!). However, you can request to “snap” a user to a known venue and to search for recommended coffee spots nearby using the Foursquare API. Within FoursquareService, we have defined two methods that will perform these functions.

The endpoints provided by the Foursquare API are generally access via HTTP. Within the Android environment, these HTTP requests are represented as Retrofit Call definitions, which we can see within FoursquareService:

Above, you can see each HTTP request within the @GET annotations. Note that there are a few mandatory parameters when using search via the Foursquare API — v, client_id, client_secret, and ll. We also specify llAcc to improve location matching. (For more details, see the Foursquare API Endpoints website.)

For snapToPlace(), we are calling the venues/search API endpoint, which returns venue results based on the specified location. We also specify an additional parameter, limit=1, so that the Call will return only the venue where the user is most likely to be at.

For searchCoffee(), we are calling the search/recommendations API endpoint, which returns recommended venues around the specified location. An additional parameter, intent=coffee, is present so that the results will only be venues related to coffee.

To form a request to the Foursquare API, we use Retrofit to create an HTTP connection and make the request. In Java, this involves the following:

• A Retrofit object with a base URL (https://api.foursquare.com/v2/) and a converter factory (using Gson here for JSON).
• A FoursquareService object that gives Retrofit access to the defined functions.
• A Call object that performs one of the FoursquareService functions, accepting parameters for client ID, client secret, and user location details.
• Invoking the Call.enqueue(Callback) method to start the request asynchronously.

For snapToPlace() and searchCoffee(), here is a code snippet from PlacePickerActivity:

With the above structure, the HTTP request will initiate when Call.enqueue(Callback) is called. This is will run asynchronously and will execute the defined callback to parse the response, once the request has completed.

Hello, JSON!

Now that we understand how to form and make requests using Retrofit, we can now say ‘Hello, JSON!’ and parse the JSON responses. Since we are using Gson as our deserialization library, converting a Foursquare API response in JSON to meaningful data in Android becomes super simple.

To understand how Gson works, let’s take a look at a sample response from a venues/search request.

In the response above, each level within the JSON has a corresponding Java Object. Therefore from this response, we’ll be using FoursquareJSON, FoursquareResponse, FoursquareVenue, and FoursquareLocation. Within each one of these classes, you can see the levels being built, down to the venue and location level. And that’s it! The Gson library will take care of everything else for you.

Now looking back at PlacePickerActivity, you should be able to see how the Java Objects are used to parse out the data from the JSON. With snapToPlace(), we have the following code snippet:

With Gson, the Java Objects will represent the structure of the response JSON, and all associated data is easily retrieved through defined variables and methods. It’s as simple as that!

Hurray, you did it!

At this point, you should be a seasoned pro at integrating Foursquare’s powerful location intelligence into your next Android app!

Just to recap, this post walked through the basics of how to retrieve venues using the Foursquare API. Here’s a quick summary how to get started with Foursquare API.

1. Become a Foursquare developer! Visit the Foursquare for Developers website and create a new app. You’ll be granted with a client ID and client secret, used to access the Foursquare API endpoints.
2. Where are you? You can use the venues/search API endpoint with the limit=1 parameter to “snap” yourself to the venue you’re at.
3. Coffee, please! Now, make a request with the search/recommendations API endpoint with the intent=coffee parameter to find recommended coffee spots around you.
4. Easy peasy! Integrating the Foursquare API with Android is simple. Using libraries such as Retrofit and Gson can greatly help with the heavy-lifting of managing HTTP connections and JSON parsing, so that you can focus on designing the next big app.

If you ever run into a snag with the Foursquare API, please feel free visit the Foursquare for Developers website for documentation on the endpoints.

Need a shiny ‘Powered by Foursquare’ logo for your app? Check out the Foursquare Press Kit for some resources.

Interested in using Foursquare’s location intelligence for your business? Explore our products and solutions on the Foursquare for Enterprise website.

Now, go forth and develop! We look forward to seeing what you build with Foursquare!