v3 Migration How-To

Generating API Keys

  1. Create a new application

  1. Generate a new token

  1. Copy and save this token

What’s changed ?
We’ve centralized token creation within the App

Practical Use Case
Create multiple tokens for many different use cases (i.e. Dev/Prod/Staging) or for different location powered experiences.

back to top

Making API Calls

Authentication

Auth for v2 is handled via URL Parameters

.../v2/venues/search?client_id={{client_id}}&client_secret={{client_secret}}

Auth in v3 is handled via an Authorization Header

‘Authorization’: fOuR5qU@r3-K3Y

back to top

Endpoint Changes: Place Search

What’s Changed?

  • Syntax changes: v2/venues/explorev3/places
  • Changed some query params naming
  • Added new query params
  • Removed some query params
  • Increased breadth and depth of venue attributes in response payload to 26 data fields across Core, Extended and Rich
  • Added the ability to customize payload response based on desired attributes using any of the above data fields.

Place Search Parameters

v2v3Did it change?How did it change?
llllNo-
nearnearNo-
radiusradiusNo-
queryqueryNo-
limitlimitNo-
categoryIdcategoriesYes“categoryID” renamed to “categories”. Functionality is the same.
n/afields (new)YesAllows you to specify which fields are returned in response. Full list here. By default, all Core Fields are returned.
n/ane (new)YesNew parameter, the lat/long representing the northeast points of a rectangle. Must be used in conjunction with “sw” parameter.
n/asw (new)YesNew parameter, the lat/long representing the southwest points of a rectangle. Must be used in conjunction with “ne” parameter.
n/asort (new)YesNew parameter, specifies the order in which results are returned. Possible values: “relevance” (this is default), “rating”, “distance”.
n/apagination in headerYesWith endpoints that return a list of results, like Places Search, we may return pagination details in the response's header when there are additional results. See link for additional information on pagination.
urln/aRemoved from v3.
providerIdn/aRemoved from v3.
linkedIdn/aRemoved from v3.

NOTE: All other v2 parameters not listed have been removed.

How to use the fields parameter
The fields parameter gives you more control in defining the venue attributes returned by the API response payload.

http://api.foursquare.com/v3/places/search?near=NYC&query=tacos&fields=id,name,geocodes,categories

Endpoint Changes: Place Details

What’s Changed?

  • Syntax changes: v2/venues/{VENUE_ID}v3/places/{FSQ_ID} where FSQ_ID is the ID of the Place/Venue.
  • Changed some query params naming
  • Added new query params
  • Removed some query params
  • Increased breadth and depth of venue attributes in response payload to 26 data fields across Core, Extended and Rich
  • Added the ability to customize payload response based on desired attributes using any of the above data fields.
v2v3Did it change?How did it change?
PATH parameter: {Venue_ID}PATH parameter: {FSQ_ID}YesSyntax
n/asession_tokenYesNew parameter, a user-generated token to identify a session for billing purposes. More info here.
n/afields (new)YesNew parameter, indicates which fields should be returned in the response, separated by commas. Core Fields returned by default, full list of available fields here.

How to use the fields parameter
The fields parameter gives you more control in defining the venue attributes returned by the API response payload.

back to top

Endpoint Changes: Place Photos

What’s Changed?

  • Syntax changes: v2/venues/{VENUE_ID}/photosv3/places/{Fsq_ID}/photos
  • Added new query params
  • Removed query params
  • Added the ability to sort the photos
  • Added the ability to select certain types of photos via classifications

Place Photos Parameters

v2v3Did it change?How did it change?
groupn/aYesRemoved.
limitlimitNo-
offsetpagination in headerYesRemoved “offset” parameter to allow for header based pagination.
n/asort (new)YesNew parameter, specifies order in which results are returned. Values: Popular (default - based on popularity by Foursquare users), Newest (most recent to least recent).
n/aclassifications (new)YesNew parameter, restricts results to photos matching specified classifications, separated by comma. Values: Food, Indoor, Menu, Outdoor.

How to use the sort and limit parameters
The new limit and sort parameters give you more control in defining the types of photos returned via the API.

How to make a call:

http://api.foursquare.com/v3/places/5a187743ccad6b307315e6fe/photos?classifications=menu,outdoor&limit=5

back to top

Endpoint Changes: Place Tips

What’s changed?

  • Removed query params

Place Tips Parameters

v2v3Did it change?How did it change?
limitlimitNo-
sortsortNo-
offsetpagination in headerYesRemoved “offset” parameter to allow for header based pagination.

How to use the sort and limit parameters
The new limit and sort parameters give you more control in defining the types of tips returned via the API.

How to make a call:

http://api.foursquare.com/v3/places/5a187743ccad6b307315e6fe/tips?sort=newest&limit=5

back to top

Endpoint Changes: Nearby Places

What’s changed?

  • Syntax changes: v2/venues/searchv3/places/nearby
v2v3Did this change?How did this change?
nearn/aYesRemoved, “ll” now required.
llllNo-
n/ahaccYesNew parameter, “horizontal accuracy”. This is the margin of error for your GPS coordinates.
altaltitudeYesUpdated parameter name from “alt” to “altitude”.
queryqueryNo-
limitlimitNo-

NOTE: All other v2 parameters not listed have been removed.

Endpoint Changes: Suggested Completion/Autocomplete

What’s changed?

  • Syntax Changes: v2/venues/suggestcompletionv3/autocomplete
v2v3Did it change?How did it change?
queryqueryNo-
llllNo-
n/aradiusYesNew parameter, defines the distance (in meters) to return the results. May not fully restrict results to specified area.
n/atypesYesNew parameter, the types of results to return. Either an address, geo, place, and/or search. If no type is specified, all types are returned.
n/asession_tokenYesNew parameter, a user-generated token to identify a session for billing purposes. More info here.
limitlimitNo-

NOTE: All other v2 parameters not listed have been removed.

Endpoint Changes: Report Venue Selection

What’s changed?

  • Syntax Changes: v2/venues/{VENUE_ID}/selectv3/place/select
v2v3Did it change?How did it change?
VENUE_IDFSQ_IDYesVENUE_IDs have been replaced with FSQ_IDs in the new API version.
requestIDrequestIDNo-
typen/aYesRemoved.
visitSignaturen/aYesRemoved.
urln/aYesRemoved.
imageURLn/aYesRemoved.
n/aselectContextYesNew parameter, a string value used to specify the use case for the request.
n/adelayedYesNew parameter, a boolean value.