Versioning is controlled by the v parameter, which is a date that essentially represents the “version” of the API you expect from Foursquare.

It is designed to give developers the freedom to adapt to Foursquare API changes on their own schedule. The value of the v parameter 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 in the future, that renames all our id fields to “foo”. If your API requests are passing in v=YYYYMMDD or smaller values, these fields will still be called id. However, once you change your parameters to a new date or greater, you will see “foo” in our responses instead.

All API requests require a version parameter. This gives give developers control over at which period in time to call our continously updating API. In order to stay up to date with the latest changes, we recommend updating your version as often as possible.

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

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

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:

  • Increase this date as often as possible (typically every couple months)
  • Check if Foursquare has made any changes since your old version
  • Modify your implementation to accommodate any 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.

To warn developers about impending changes, we will 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.