All API requests require two special parameters that give developers control over the kind of response that Foursquare returns. These required parameters are:
v parameter, which is a date that essentially represents the “version” of the API you expect from Foursquare.
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 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 &m=foursquare
The v Parameter
v parameter 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.
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.
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 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
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”) parameter 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
Unless your application evolves significantly, it seems unlikely that you will ever have to change the
m parameter values you pass in.