v3 Migration How-To

Generating API Keys

Create a new application

Generate a new token

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/explore → v3/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

v2	v3	Did it change?	How did it change?
ll	ll	No	-
near	near	No	-
radius	radius	No	-
query	query	No	-
limit	limit	No	-
categoryId	categories	Yes	“categoryID” renamed to “categories”. Functionality is the same.
n/a	fields (new)	Yes	Allows you to specify which fields are returned in response. Full list here. By default, all Core Fields are returned.
n/a	ne (new)	Yes	New parameter, the lat/long representing the northeast points of a rectangle. Must be used in conjunction with “sw” parameter.
n/a	sw (new)	Yes	New parameter, the lat/long representing the southwest points of a rectangle. Must be used in conjunction with “ne” parameter.
n/a	sort (new)	Yes	New parameter, specifies the order in which results are returned. Possible values: “relevance” (this is default), “rating”, “distance”.
n/a	pagination in header	Yes	With 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.
url	n/a		Removed from v3.
providerId	n/a		Removed from v3.
linkedId	n/a		Removed 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.

v2	v3	Did it change?	How did it change?
PATH parameter: {Venue_ID}	PATH parameter: {FSQ_ID}	Yes	Syntax
n/a	session_token	Yes	New parameter, a user-generated token to identify a session for billing purposes. More info here.
n/a	fields (new)	Yes	New 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}/photos → v3/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

v2	v3	Did it change?	How did it change?
group	n/a	Yes	Removed.
limit	limit	No	-
offset	pagination in header	Yes	Removed “offset” parameter to allow for header based pagination.
n/a	sort (new)	Yes	New parameter, specifies order in which results are returned. Values: Popular (default - based on popularity by Foursquare users), Newest (most recent to least recent).
n/a	classifications (new)	Yes	New 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

v2	v3	Did it change?	How did it change?
limit	limit	No	-
sort	sort	No	-
offset	pagination in header	Yes	Removed “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/search → v3/places/nearby

v2	v3	Did this change?	How did this change?
near	n/a	Yes	Removed, “ll” now required.
ll	ll	No	-
n/a	hacc	Yes	New parameter, “horizontal accuracy”. This is the margin of error for your GPS coordinates.
alt	altitude	Yes	Updated parameter name from “alt” to “altitude”.
query	query	No	-
limit	limit	No	-

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

Endpoint Changes: Suggested Completion/Autocomplete

What’s changed?

Syntax Changes: v2/venues/suggestcompletion → v3/autocomplete

v2	v3	Did it change?	How did it change?
query	query	No	-
ll	ll	No	-
n/a	radius	Yes	New parameter, defines the distance (in meters) to return the results. May not fully restrict results to specified area.
n/a	types	Yes	New 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/a	session_token	Yes	New parameter, a user-generated token to identify a session for billing purposes. More info here.
limit	limit	No	-

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

Endpoint Changes: Report Venue Selection

What’s changed?

Syntax Changes: v2/venues/{VENUE_ID}/select → v3/place/select

v2	v3	Did it change?	How did it change?
VENUE_ID	FSQ_ID	Yes	VENUE_IDs have been replaced with FSQ_IDs in the new API version.
requestID	requestID	No	-
type	n/a	Yes	Removed.
visitSignature	n/a	Yes	Removed.
url	n/a	Yes	Removed.
imageURL	n/a	Yes	Removed.
n/a	selectContext	Yes	New parameter, a string value used to specify the use case for the request.
n/a	delayed	Yes	New parameter, a boolean value.