Migrate to Newest Places API Version

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’: [email protected]

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

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}/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

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/searchv3/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/suggestcompletionv3/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}/selectv3/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.


Did this page help you?