Versioning & Internationalization

Versioning

All requests require a v=YYYYMMDD parameter, which is a date that essentially represents the "version" of the API you expect from Foursquare. Please note that this applies to every API request, including POST requests.

We'll try to minimize breaking changes we make to the API, but when we do make these changes, we will use this parameter to give you time to transition to the new implementation. For example, if a change occurs on October 17, 2013, all requests using v=20131016 or an earlier date will not be affected. Clients that wish to be robust against changes should always pass v=DATEVERIFIED (in the YYYYMMDD format) and watch for any deprecated responses coming back from the server.

Requests using deprecated versions and endpoints will at first return 200s, and they will also contain errorType deprecated in the meta section of the response. 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.

As of January 28, 2014, requests that do not include a v parameter will be rejected.

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.