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.
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
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}
whereFSQ_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.
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
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
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. |