Migration Guide
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 your 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 Place Match endpoint in the coming months.
Autocomplete Endpoints
| Old Endpoint - Host: api.foursquare.com | New Endpoint- Host: places-api.foursquare.com |
|---|---|
| api.foursquare.com/v3/autocomplete | places-api.foursquare.com/autocomplete |
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 |
| api.foursquare.com/v3/places/match | places-api.foursquare.com/places/match |
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.:
Header Authentication String
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
You can learn more about the Places API pricing here .