As you begin to migrate from the integrated Places dataset to the FSQ Places dataset, Foursquare is here to help make this transition as smooth as possible. Please see below for a list of best practices and technical guidance, related to schemas, chains, categories, quality filtering, and access to a sample of our evolved Places dataset.
Schema
Our schema has changed - many of our non-core integrated Places attributes have been removed from the FSQ Places dataset, for reasons such as very low “fill rates” (meaning the percentage of POIs that have a non-null value for a given attribute), a change in Foursquare’s stance on the value of a given attribute, etc.The majority of these attributes were included in the “Tags” package, and almost every attribute has an analog in the new dataset.
Only one new attribute has been added, placemaker_url. This is the URL for the Placemaker tool for this place.
One attribute has been renamed, fsq_id is now fsq_place_id. This is the primary key for all places.
The notable deprecations are fax, our various geocodes (including front_door, drop_off, roof, and main, where applicable - the primary latitude and longitude of the place remain as standalone OS-package attributes), venue_reality_bucket, closed_bucket (see below for more information on the removal of the previous two attributes), existence, provenance_rating, address_extended (the core address attributes remain in the OS and Pro packages), hours_display (hours and hours_popular remain in the Premium package), and merged_place_ids.
The notable data-type changes are fsq_category_labels, photo_labels, and tips.
The notable value format changes are fsq_category_ids and fsq_chain_ids. See below for more information on these. In addition, both country and price attributes are now in Uppercase, such as ‘US’ and “EXPENSIVE”.
To view our full schema changes, please download the following file:
Chains
Our ChainID values have changed format - in the integrated Places dataset, the value for fsq_chain_ids were UUIDs, and we have since reverted to 16-character alphanumeric BSON IDs. Labels / names have not changed, only the IDs have.
In addition, Foursquare has placed a renewed emphasis on chain quality and coverage. We now provide a “chains” file alongside our FSQ Places deliveries, which includes a column indicating Foursquare’s confidence about our quality of said chain. We also have significantly expanded our coverage of global chains in FSQ Places.
To view a mapping between integrated Places fsq_chain_ids and FSQ Places chain_ids, please download the "fsq_places_chain_mapping_guide.tsv.zip" the following file:
Categories
Similar to chains, our CategoryID values have changed format - in the integrated Places dataset, the value for fsq_category_ids were 5-digit integers, and we have since reverted to 16-character BSON IDs. Labels / names have not changed, only the IDs have.
To view a mapping between integrated Places fsq_category_ids and FSQ Places category_ids, please download the following file:
Sample dataset
We have provided a 500 row sample of the FSQ Places dataset, available for download in TSV format. Please download the following file:
Quality filter guidance
Deprecation of closed_bucket and venue_reality_bucket attributes
Two of the core attributes in the integrated Places dataset, venue_reality_bucket and closed_bucket, have been deprecated in FSQ Places and will no longer be supported or offered by Foursquare moving forward. The intent behind this change is to move away from modeled attributes such as these, and towards concrete values that are high-confidence indicators about when a place last had some meaningful interaction with a human or input from a data source, or when a human or data source marked a place as closed in our dataset.
Many Foursquare customers using our integrated Places dataset chose to implement an additional quality filter post-ingestion, to ensure that places irrelevant or deemed to be of insufficient quality were filtered out of their production use case. With the deprecation of venue_reality_bucket and closed_bucket, which were typically two of the main attributes used in filtering, there will be a need to re-implement said quality filter.
Values for the old venue_reality_bucket included: VeryHigh, High, Medium, Low, and VeryLow. The values represented the confidence Foursquare had that a given place exists in the real world. Our “quality cut” dataset filtered only for VeryHigh and High places.
The attribute venue_reality_bucket should be replaced with the date_refreshed attribute. If you have historically filtered by venue_reality_bucket in (‘VeryHigh’, ‘High’), then our recommendation is to filter by date_refreshed >= today - 1 year.
Values for the old closed_bucket included: VeryLikelyOpen, LikelyOpen, Unsure, LikelyClosed, and VeryLikelyClosed. The values represented the confidence Foursquare had that a given place was open for business or visitation in the real world.
The attribute closed_bucket should be replaced with the date_closed attribute. This value will indicate at what date a given place was marked as closed in Foursquare’s dataset. This does not always indicate the date on which a place closed for business or visitation in the real world.
The date_closed attribute also does not represent temporary, seasonal, or holiday closures. It indicates that a given place has permanently ceased its business operations.