Versioning is controlled by the v parameter, which is a date that represents the "version" of the API for which 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 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 developers control over the time period in which to call our continuously updated 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 this:
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 of 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. Please note 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
As Foursquare continues to grow and evolve, we will occasionally need to deprecate certain API endpoints and versions. Responses to requests using deprecated versions and endpoints will contain useful information in the meta section of the response—look for the errorType in deprecated fields. 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.