Client Resources

Documentation to help developers integrate foursquare into client applications

User Authentication


To perform user authentication on an iOS or Android application, we recommend using our native auth flow that lets your users authenticate using their existing credentials in their Foursquare application.

On other phone platforms (e.g., Blackberry), we recommend embedding a web browser and using the OAuth2 token flow. At the end of this flow, the user is redirected to a page on your domain—this may be a dummy page if you have no real server component.

For more details on authentication see our authentication page.

Android

Android intents are ways to link directly into the native foursquare application on Android. If you’re planning to embed a link in a platform-independent medium (like a website, NFC tag, QR Code, etc.) we recommend you use Android intents for now, as they degrade nicely to the mobile website on other platforms. Currently supported intents are:

View a venue http://foursquare.com/venue/VENUE_ID
Start specific search intent (immediate) http://foursquare.com/search?q=ENCODED_QUERY&immediate=1
Show friend activity, like the Friends tab http://foursquare.com/feed

iPhone

Developers interested in linking to the foursquare iPhone application can use the following URLs to launch the application into specific views. These custom URLs also work with the native Android and Blackberry clients, but may behave unexpectedly if the client is not installed on the user's phone.

Show a venue foursquare://venues/VENUE_ID
Show a check-in foursquare://checkins/CHECKIN_ID
Show a tip foursquare://tips/TIP_ID
Show a user foursquare://users/USER_ID

We recommend that you attempt to link to these URLs only if the user has the foursquare application installed on their device. Please refer to the "Opening a URL Resource" section in the UIApplication documentation for more information.

Native App Integration

If you add a text or photo post to a check-in, you can have this link directly to relevant screens within your native iOS or Android app. Native apps can register predefined custom URL schemes, where each app-specific custom URL scheme corresponds to a different action inside of foursquare.

The custom URL scheme for each action type is of the form:

fsq+LC_CLIENT_ID+ACTION_TYPE://
      

where LC_CLIENT_ID is the app’s lowercase client ID.

All action links include a fsqCallback URL which is a deeplink back to the originating foursquare screen. We strongly suggest that apps place a back button labeled “foursquare” (or use our favicon) in the top left side of the landing screen or automatically redirect the user after they complete an action in the app. More users will choose to leave foursquare and enter connected apps if it is easy for them to return back to where they started.

To support an action, register its corresponding scheme in the app’s build:

  • For iOS, URL schemes are registered via your app’s .plist configuration file
  • For Android, URL schemes are registered with intent-filters in your app’s manifest file.

We support two types of actions:

Authorize: Take the user to a screen in the app to connect their account with foursquare.

fsq+byn1jkaupquyj35bhzhaqnaed1uyb410+authorize://?
      fsqCallback=CALLBACK_URL
      

Post: Display the specified post inside the app.

fsq+byn1jkaupquyj35bhzhaqnaed1uyb410+post://?
      contentId=CONTENT_ID&
      fsqCallback=CALLBACK_URL
      

The contentId parameter for post and reply is an identifier given by the app when creating the corresponding content.

NFC

The Foursquare apps for Android and Blackberry support reading of NFC tags for venues. The basic idea is to put a url for a venue on a tag, a user taps the tag with their device, and the Foursquare app wakes up, loading that specific venue page.

In order to do this, you need an NFC tag, an app that can write to the tag, and the url of the venue you want to embed.

There's a free tag-writer app on marketplace which we recommend for writing the url: https://market.android.com/details?id=com.nxp.nfc.tagwriter

Next get the venue ID of the venue you want to use. Write the following url pattern onto the tag:

          http://foursquare.com/venue/VENUE_ID
      

Replace VENUE_ID with the ID of the venue you want.

That's it. You can try tapping an NFC-capable phone to the tag, and you'll see the Foursquare app read it.