The Places API is now built on the Open Source Places dataset, offering a variety of improvements to quality, available fields, and structure. API users can expect to see improved search results and greater accuracy for location-based queries. You can use the Places API in conjunction with the Users API to create an authenticated experience for you user.
Path Changes
The endpoints for the Places API and Users API have changed, notably removing the version segment (/v3/ or /v2/). Versioning will now be managed via the header, where you may specify a date. We will be releasing updated versions of the Autocomplete and Place Match endpoints in the coming months.
Search & Data Endpoints
| Old Endpoint - Host: api.foursquare.com | New Endpoint- Host: places-api.foursquare.com |
|---|---|
| api.foursquare.com/v3/places/search | places-api.foursquare.com/places/search |
| api.foursquare.com/v3/places/{fsq_id} | places-api.foursquare.com/places/{fsq_place_id} |
| api.foursquare.com/v3/places/{fsq_id}/tips | places-api.foursquare.com/places/{fsq_place_id}/tips |
| api.foursquare.com/v3/places/{fsq_id}/photos | places-api.foursquare.com/places/{fsq_place_id}/photos |
Placemaker Endpoints (formerly Feedback Endpoints)
| Old Endpoint - Host: api.foursquare.com | New Endpoint- Host: places-api.foursquare.com |
|---|---|
| api.foursquare.com/v3/places/{fsq_id}/proposeedit | places-api.foursquare.com/places/{fsq_place_id}/suggest/edit |
| api.foursquare.com/v3/places/{fsq_id}/flag | places-api.foursquare.com/places/{fsq_place_id}/suggest/remove places-api.foursquare.com/places/{fsq_place_id}/suggest/merge |
| api.foursquare.com/v3/feedback/status | places-api.foursquare.com/suggest/status |
| -- | places-api.foursquare.com/places/{fsq_place_id}/flag (NEW) |
| -- | places-api.foursquare.com/places/suggest/place (NEW) |
User Management Endpoints
| Old Endpoint - Host: api.foursquare.com | New Endpoint- Host: users-api.foursquare.com |
|---|---|
| api.foursquare.com/v2/usermanagement/createuser | users-api.foursquare.com/users/managed-user/create |
| api.foursquare.com/v2/usermanagement/deleteuser | users-api.foursquare.com/users/managed-user/delete |
| api.foursquare.com/v2/usermanagement/refreshtoken | users-api.foursquare.com/users/managed-user/refresh-token |
Geotagging Endpoints
| Old Endpoint - Host: api.foursquare.com | New Endpoint- Host: places-api.foursquare.com |
|---|---|
| api.foursquare.com/v3/places/nearby | places-api.foursquare.com/geotagging/candidates |
| api.foursquare.com/v3/place/select | places-api.foursquare.com/geotagging/confirm |
Auth Changes
We've migrated our authentication system from API keys to service keys, which offer enhanced security, better management, and more granular access control. The Legacy V3 Places API all support this new Service key Authentication method to make your migration easier.
| Old Auth | New Auth |
|---|---|
| Method: API Keys | Method: Service Keys |
Header: Authorization: <API_KEY> | Header: Authorization: Bearer <SERVICE_KEY> |
Request Changes
Versioning
We’ve added date-based versioning to this API to ensure stability and compatibility; please include the version date in the header, e.g.:
X-Places-Api-Version: 2025-06-17
X-Users-Api-Version: 2025-06-17
Note that the versions are separated by API (Users vs. Places APIs) and may not always have the same version date.
We will update versions for breaking changes only. We will not update a version if a field gets added to a response.
Response Changes
The following changes have been made to the Response object
Fields
| Old Field | New Field(s) | Notes |
|---|---|---|
fsq_id | fsq_place_id | Consumers of our flat file schema will now find ID parity between the flat file and the API. |
categories | categories (unchanged) | The ID returned in the categories JSON is now a BSON category ID instead of an integer. Categories are documented here. |
location | location (unchanged) | The dma and census_block have been removed from this section of the response and will be moved to extended_location |
photos | photos (unchanged) | We've released a new classification model on photos. |
geocodes | latitude, longitude | These coordinates are the main entry point of the POI. |
features | attributes | Renamed. |
| n/a | extended_location | New extended location object containing dma and census_block |
timezone | Removed | No longer available. |
closed_bucket | Removed | No longer available. Use the existence of date_closed instead. |
fax | Removed | No longer available. |
verified | Removed | No longer available. |
Pricing Changes
You can learn more about the Places and Users APIs pricing here.
For customers that joined before June 2, 2025, your pricing will change on September 1, 2025 to reflect the current pricing. If you are still using v3 or v2 endpoints at that time, they will be charged at a $18.75 CPM.
For customers that join between June 2, 2025 and June 17, 2025, your pricing will change on July 1, 2025 to reflect the current pricing. If you are still using v3 or v2 endpoints at that time, they will be charged at a $18.75 CPM.
Customers who join after June 17, 2025 do not have access to v2 or v3 endpoints.
If you have further questions about migration, please contact us for assistance.