Places Pro and Premium Data Schemas
Overview
Foursquare Places Pro and Premium are two tiers of the next-generation Places dataset, powered by Foursquare's proprietary Places Engine. This enhanced methodology streamlines and enhances how POI data is generated, updated, and validated.
Using advanced machine learning models like Geosummarizer and Harmonizer, the Places Engine synthesizes data from a variety of sources, including web crawls, data syndicators, and partnerships with data providers. Robust human validation further ensures that the data scales efficiently and maintains accuracy, aligning closely with real-world locations.
Places Pro Tier Dataset
| Column Name | Type | Description |
|---|---|---|
| fsq_place_id | String | The unique identifier of a Foursquare POI (formerly known as venueid or fsq_id). Use this ID to view a venue at foursquare.com by visiting: https://foursquare.com/placemakers/review-place/{fsq_place_id} |
| name | String | Business name of a POI |
| latitude/longitude | Decimal | Foursquare latitudes and longitudes are delivered as decimal degrees (WGS84 datum). Default geocode type is front door or rooftop, where available These are derived by a combination of: Direct input from third party sources Direct input of precise latitude/longitude (a pin drop) from initial user creation and correction |
| address | String | User-entered street address of the venue |
| locality | String | City, town or equivalent the POI is located in. |
| region | String | State, province, territory or equivalent. Abbreviations are used in the following countries (US, CA, AU, and BR). Remaining countries use full names. |
| postcode | String | Postal code of the POI, or equivalent (zip code in the US). Format will be localized based on country (i.e. 5-digit number for US postal code) |
| admin_region | String | Additional sub-division. Usually, but not always, a country sub-division (e.g., Scotland) |
| post_town | String | Town/place employed in postal addressing. May not reflect the formal geographic location of a place |
| po_box | String | Post Office Box |
| country | String | 2 Letter ISO Country Code |
| date_created | Date | The date the POI entered our database. This does not necessarily mean the POI actually opened on this date. |
| date_refreshed | Date | The date the POI last had any single reference refreshed from crawl, Listing Syndicators, users or human validation |
| date_closed | Date | The date the POI was marked as closed in our database. This does not necessarily mean the POI actually closed on this date. |
| tel | String | Telephone number of a POI with local formatting |
| website | String | URL to the POI’s (or the chain’s) publicly available website |
| String | Primary contact email address of organization, if available | |
| facebook_id | String | This POI's Facebook ID, if available |
| String | This POI's Instagram handle, if available | |
| String | This POI's Twitter handle, if available | |
| fsq_category_ids | Array (String) | ID (or IDs) of the most granular category (or categories) available for this POI. See our Categories page for more details |
| fsq_category_labels | Array(String) | Label (or labels) for the most granular category (or categories) available for this POI. See our Categories page for more details |
| name_translated | String (JSON) | User-entered translated name(s) of a venue. The translated name will also include a ISO 639-1 language code and follows the following format: [{Translated Venue Name,language code(en for English, ja for Japanese, etc)}]. Note that most POIs will not include a translated name. Generally, this attribute will only exist for very popular POIs. |
| neighborhoods | Array(String) | The neighborhood(s) or other informal geography in which this POI is found |
| census_block_id | String | The 15-digit Census Block GEOID for the census block which contains the latitude and longitude of the POI - e.g. census_block_id=360610058003001 - populated only for Places within the United States. |
| dma | String | DMA ( Designated Market Area, as defined by Nielsen) the POI is located in. This signifies a region where the population can receive similar TV and radio offerings in the USA. There are 210 DMAs in the United States. |
| fsq_chain_ids | Array(String) | The chain ID(s) of a POI. Use in conjunction with fsq_chain_name. See our Chains page for more details. |
| fsq_chain_names | Array(String) | Standardized chain name of a POI. Use in conjunction with fsq_chain_id. See our Chains page for more details. |
| chain_store_id | String | The unique ID assigned to a venue in order to differentiate it from other stores within the same chain. |
| subvenue_count | String | If a POI is a parent POI (with child POIs, e.g. a mall), total sub-venues will indicate how many POIs this POI is a parent of (how many stores are in this mall) |
| parent_id | String | The Foursquare ID of a POI’s parent venue. Foursquare maintains parent/child relationships for POIs located inside POIs (e.g. stores in malls) |
| placemaker_url | String | A link to the POI’s review page in the PlaceMaker Tools application. Users can suggest edits to correct data quality issues or review pending edits. See Placemaker page for more details. |
| unresolved_flags | Array(String) | A set of quality issue flags reported by Placemakers, human or agent, that require further corroboration. Each flag marks a suspected problem that has not yet been resolved. The values can be one or more of the following: - closed – the venue is believed to be permanently closed - duplicate – the venue is a duplicate of another record - delete – the venue should be removed entirely - privatevenue – the venue is private and should not be publicly listed - inappropriate – the content violates policy or is otherwise unsuitable - doesnt_exist – the venue is thought not to exist at the specified location |
Places Premium Tier Dataset
All attributes from Places Pro, plus your selection of rich attributes:
| Column Name | Type | Description |
|---|---|---|
| hours | String (JSON) | This attribute contains a JSON representation of hours of operation. Sample format: {"saturday":[["9:00","18:00"]],"tuesday":[["9:00","18:00"]],"friday":[["9:00","18:00"]],"thursday":[["9:00","18:00"]],"wednesday":[["9:00","18:00"]],"monday":[["9:00","18:00"]]} The open time and close time are represented by local, 24hr time of the POI (so no need to convert for timezones) |
| hours_popular | List of lists | Hours of the week when people typically visit a place. Foursquare’s popular hours algorithm is calculated in the following way: Calculate a histogram of check-ins per time bin. There are 168 time bins, one for each hour of the week. Find time bins that have a specified percentage more check-ins than the average time bin and label these as popular. Fill in any one hour gaps with the rule: if the hour before is popular and the hour after is popular, then the hour in the middle is also popular.A POI must have a minimum number of check-ins to be considered for the calculation.The popular hours attribute follows the same format as the hours attribute. |
| total_photos | BigInt | Total number of photos users have submitted for a particular POI (all-time) |
| photos | Ordered Array(Strings) | A url that links to the photos submitted by our users. They are ranked by the TrueSkill algorithm and ordered by ranking within the array |
| photo_labels | Map (String, String) | Photo labels for the corresponding top 25 photos, where the key is photoUrl and the value is labels |
| total_tips | BigInt | Total number of tips users have submitted for a particular POI (all-time) |
| tips | Ordered Array(Arrays) | Recommendations (or warnings) posted by our users on our site and in our apps. This is an open text box. Tips are ranked by the amount of times a tip was liked and ordered by ranking alongside the TipID within the array. |
| tastes | Ordered Array(Strings) | Tastes are nouns or noun-phrases that signify unique qualities of the POI. These are extracted using NLP from tips and shouts from Foursquare apps. Tastes are ranked using a combination of affinity and frequency, and are ordered by ranking within the array. |
| rating | Float | The rating of a POI (0-10) based on user votes as well as an internal score aggregated by likes /dislikes, tips, and visit traffic |
| price | String | A description of the price of a POI's offerings on the following scale: Cheap, Moderate, Expensive, Very Expensive |
| description | String | General description of a POI - this is a free form box. Updated by POI owner or typically managed/edited by Superusers |
| popularity | String | Measure of a POI's popularity by foot traffic. This score is on a 0 to 1 scale and uses a 6-month span of POI visits. The most popular POI in the geographic area is assigned the score .9999. This score is calculated across all POIs within the same country. |
| atm | Boolean | This attribute denotes whether a POI has an ATM available (True or False) |
| delivery | Boolean | This attribute denotes whether a POI delivers food or drink (True or False) |
| hasparking | Boolean | This attribute denotes whether a POI has parking (True or False) |
| reservations | Boolean | This attribute denotes whether a POI offers reservations (True or False) |
| outdoorseating | Boolean | This attribute denotes whether a POI offers outdoor seating (True or False) |
| restroom | Boolean | This attribute denotes whether a POI has restrooms (True or False) |
| takescreditcards | Boolean | This attribute denotes whether a POI takes credit cards (True or False) |
| wifi | String | This attribute denotes whether a venue has WiFi. May be "t","f","p","n", or "fp" (true, free, paid, no wifi, free or paid) |
| veracity_rating | BigInt | A 1 to 5 star quality rating indicating how complete, current, and reliable the location's information is, helping you understand how strong our data signals are for this place.
5 = Highly reliable and complete information, regularly updated from trusted sources and real user activity.
4 = Very good information verified from reliable sources with some user engagement.
3 = Good essential information from multiple sources that's generally current but less frequently updated.
2 = Basic information available but some details may be missing or outdated.
1 = Limited information from few sources that may not have been updated recently. |
Category Dataset
| Column Name | Type | Description |
|---|---|---|
| category_id | String | The unique identifier of the Foursquare category; represented as a BSON. |
| category_level | Integer | The number of levels within the category’s hierarchy; accepted values 1-6. |
| category_name | String | The name of the most granular category in the category hierarchy. |
| category_label | String | The full category hierarchy using > to indicate category breadcrumb. |
| level1_category_id | String | The unique identifier for the first level category in the hierarchy. |
| level1_category_name | String | The name for the first level category in the hierarchy. |
| level2_category_id | String | The unique identifier for the second level category in the hierarchy. |
| level2_category_name | String | The name for the second level category in the hierarchy. |
| level3_category_id | String | The unique identifier for the third level category in the hierarchy. |
| level3_category_name | String | The name for the third level category in the hierarchy. |
| level4_category_id | String | The unique identifier for the fourth level category in the hierarchy. |
| level4_category_name | String | The name for the fourth level category in the hierarchy. |
| level5_category_id | String | The unique identifier for the fifth level category in the hierarchy. |
| level5_category_name | String | The name for the fifth level category in the hierarchy. |
| level6_category_id | String | The unique identifier for the sixth level category in the hierarchy. |
| level6_category_name | String | The name for the sixth level category in the hierarchy. |
Chains Dataset
| Column Name | Type | Description |
|---|---|---|
| chain_id | String | The unique identifier of the Foursquare chain. |
| chain_name | String | The name of the Foursquare chain. |
| parent_chain_id | String | The unique identifier of the parent chain if applicable. |
| classification | String | The status of the chain; possible values: - VALID - CURATED - DEFUNCT |