Versioning & Internationalization

Versioning

All API requests require two special parameters that give developers control over the kind of response that Foursquare returns. These required parameters are:

  1. A v parameter, which is a date that essentially represents the "version" of the API you expect from Foursquare
  2. An m parameter, which specifies whether you want Swarm- or Foursquare-style responses.

You should send these parameters with every API request, including POST requests. Thus, a valid, fully-formed API request that includes these params looks like:

https://api.foursquare.com/v2/venues/search
  ?client_id=CLIENT_ID
  &client_secret=CLIENT_SECRET
  &ll=40.7,-74
  &query=sushi
  &v=20140806
  &m=foursquare
      

The v Parameter

The v param is designed to give developers the freedom to adapt to Foursquare API changes on their own schedule. The value of the v param is essentially a date in YYYYMMDD format that lets you tell us "I'm prepared for API changes up to this date." As a concrete example, suppose we introduce a change on October 17, 2013, that renames all our id fields to foo. If your API requests are passing in v=20131016 or smaller values, these fields will still be called id. However, once you change your parameters to v=20131017 or greater, you will see foo in our responses instead.

We recommend setting a single date across all your API calls and launching your app with API calls using this date. Our suggestion is to 1) increase this date once every few months, 2) check if Foursquare has made any changes since your old version, and 3) modify your implementation to accommodate for these changes.

Under no circumstances should you always pass in the current date. Please choose a single date and don't increase it until you are ready to accept any possible changes we've made. Note also that the version parameter passed in with each request has nothing to do with the v2 as part of our API's URL path—that should always be v2.

Deprecation

We will occasionally need to deprecate certain parts of the API and API versions as Foursquare continues to grow and evolve. Responses to requests using deprecated versions and endpoints will contain useful information in the meta section of the response—look out for an errorType of deprecated. Over time, we will phase out support for legacy behavior and versions of the API, but we expect to allow at least several months for any transitions.

Note: As of July 1, 2014, versions that are earlier than 20120609 are officially unsupported, and requests sent with them will be summarily rejected.

Note: As announced in our August 2014 update, you should stop relying on certain API endpoints, as they will be deprecated by 2015.

To warn developers about impending changes, we will often email developers who will be affected by the changes as well as conduct "API brownouts" before the changes go live to simulate the effects of the changes. For this reason, please actively monitor the email address associated with your Foursquare developer account.

The m Parameter

This parameter is required only if your v parameter is >= 20140806 and accepts values of foursquare or swarm.

Since there is only a single API that powers both Swarm and Foursquare, sometimes it makes sense for the same endpoint to return different information in its response, depending on context. The m (for "mode") param gives developers control over whether they want Swarm- or Foursquare-style API responses—for example, the Users Detail endpoint might return information check-ins with m=swarm but information about a user's tips with m=foursquare.

Unless your application evolves significantly, it seems unlikely that you will ever have to change the m param values you pass in.

Internationalization

You can specify the locale by setting the Accept-Language HTTP header in your request. Alternatively, you can add a locale=XXX parameter to your request but HTTP header specification is preferred. We currently support en (default), es, fr, de, it, ja, th, tr, ko, ru, pt, and id.

If nothing is specified, for geographical entities (e.g., city names), we'll fall back to using the language that's most popular in the country for that venue.

Foursquare also supports many country-specific subcategories in our venue categories. "Suggested Countries" are listed in our category tree for categories that we think will only apply in certain countries.