Places Data Schema
Foursquare’s Places Flat File comes with 25 core attributes and a multitude of rich attributes. Core attributes are included in all of our packages, while rich attributes are available as add-ons to any standard country or region package at an additional charge.
Glossary
Below are a list of common terms (in alphabetical order) that appear throughout this schema.
- Attribute - individual venue fields.
- Chain - There is no hard-and-fast definition of a chain; it may be privately held local chain with only a few stores, or a publicly held national brand with thousands of locations. Foursquare assigns a chain when similar venues appear in our database. Keep in mind, while there may be some variations in venue name at the venue level, chains have a single name and are given a unique Chain ID.
- Check-in (active) - A confirmed visit from a user of the Foursquare City Guide or Swarm app
- Subvenue - Individual, smaller venues that are located within a larger super-venue (see Super-venue)
- Super-venue - a venue that contains one or more other venues. Example: mall or airport.
- Superusers - Dedicated and passionate members of our community who help keep Foursquare places organized behind the scenes. Superusers create and edit venues, organize and generally maintain our database, report bugs, and provide quality feedback
- Tag - Descriptors that are appended to a specific venue or chain. For a full tag list, see table in Extended Attributes section.
- POI - A place that is directly created by our Foursquare Swarm or City Guide community, and is verified by Foursquare’s Superuser user base. All Foursquare venues are given a unique parent id that is never reused. If similar venues are appearing in the database, a unique Chain ID will be created.
Core Attributes
| Column Name | Type | Description |
|---|---|---|
| fsq_id | String | The unique identifier of a Foursquare POI (formerly known as venueid). Use this ID to view a venue at foursquare.com by visiting: http://www.foursquare.com/v/{Foursquare ID} |
| name | String | Business name of a POI |
| 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 |
| latitude/longitude | Decimal | Foursquare latitudes and longitudes are delivered as decimal places (WGS84 datum), where the value does not exceed 6 decimal places. 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 |
| geocodes | String(JSON) | Set of geocodes for the POI including rooftop, front_door and drop_off, where available; e.g. {roof={latitude=43.437061, longitude=-84.004431}, drop_off={latitude=43.43674, longitude=-84.004434}, main={latitude=43.437061, longitude=-84.004431}} |
| address | String | User-entered street address of the venue |
| address_extended | String | Additional address, incl. suite numbers |
| locality | String | City, town or equivalent the POI is located in. |
| 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. |
| 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) |
| country | String | 2 Letter ISO Country 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 |
| neighborhood | Array(String) | The neighborhood(s) or other informal geography in which this POI is found |
| po_box | String | Post Office Box |
| 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 |
| fsq_category_ids | Array(Integers) | 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(Arrays) | Label (or labels) for the most granular category (or categories) available for this POI. See our Categories page for more details |
| fsq_chain_id | Array(String) | The chain ID(s) of a POI. Use in conjunction with fsq_chain_name |
| fsq_chain_name | Array(String) | Standardized chain name of a POI. Use in conjunction with fsq_chain_id |
| 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) |
| 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) |
| 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. |
| closed_bucket | String | Probability that a POI is Open/Closed. VeryLikelyOpen, VeryLikelyClosed: 95% Confidence that a POI is Open/Closed respectively. LikelyOpen, LikelyClosed: 80% Confidence that a POI identified as LikelyOpen/VeryLikelyOpen is Open. Similarly, 80% Confidence that a POI marked as LikelyClosed/VeryLikelyClosed is Closed. Unsure: All the remaining POIs. Notes: For filtering Open POIs, depending on the level of precision that customers need, they could use “VeryLikelyOpen” [Highest Precision] > “VeryLikelyOpen+LikelyOpen” > “VeryLikelyOpen+LikelyOpen+Unsure" |
Rich Attributes
Ratings, Hours & Social Media
| 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. |
| hours_display | String | String representation of hours of operation |
| tel | String | Telephone number of a POI with local formatting |
| website | String | URL to the POI’s (or the chain’s) publicly available website |
| fax | String | Fax number in local formatting, if available |
| 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 | |
| description | String | General description of a POI - this is a free form box. Updated by POI owner or typically managed/edited by Superusers |
| 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 |
Tips and Tastes
| Column Name | Type | Description |
|---|---|---|
| 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. |
| total_tips | BigInt | Total number of tips users have submitted for a particular POI (all-time) |
Best Photos
| Column Name | Type | Description |
|---|---|---|
| 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 |
Calculated Scores
| Column Name | Type | Description |
|---|---|---|
| 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. |
| venue_reality_bucket | String | This attribute represents how “real” Foursquare believes a venue to be. As venues can be submitted directly by users, Foursquare uses a proprietary algorithm to assess real venues (public places like a popular restaurant, store, concert venue, etc) vs a private or nonexistent venue. Foursquare’s Venue Reality algorithm uses a combination of explicit and implicit signals (examples include number of searches on Foursquare, number of photos/tips submitted, number of check-ins, etc) to bucket venues with an output of Low, Medium, High, VeryHigh. Notes on attribute level filtering: Our standard data deliveries automatically exclude POIs where _venue_reality_bucket = “Low”. |
| provenance_rating | String | This attribute utilizes a heuristic to classify sources that contribute data to a given Foursquare POI. Each value represents how authoritative we believe the source to be. We place a priority on data from first party sources when we can get it, but we believe that data from third party sources is still accurate, just less authoritative. 1 = POI contains authoritative data directly from the chain, a store-locator crawl or a listing syndicator (like Yext, Uberall, etc.) 2 = POI contains data validated by human annotators employed by Foursquare from within the last 2 years (and does not qualify as a 1). 3 = POI contains user-generated data from Foursquare users, including superusers (and does not qualify as a 1 or 2). 4 = POI does not contain any of the above (i.e. only contains crawl data from open web sources, such as restaurant directories, hotel directories, etc.). Each POI will have one rating to reflect the whole POI (there will not be an array of provenance ratings for each individual attribute). If data within a POI comes from multiple sources, source types will be ranked, and the provenance_rating will be based on the highest source type on the ranked list. Notes on attribute level filtering: We do not filter our standard data deliveries based on provenance_rating as we believe all sources contribute valuable data to our Places dataset. Again, a POI that is purely sourced from crawl can be as accurate or current as a POI from other provenance_rating buckets. In those cases, such POIs have yet to be sourced from authoritative sources or user inputs. We hope to move more POIs to the higher provenance_rating over time by gathering more authoritative sources. |
| 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 |
Tags
| Column Name | Type | Description |
|---|---|---|
| atm | Boolean | This attribute denotes whether a POI has an ATM available (True or False) |
| beer | Boolean | This attribute denotes whether a POI has beer available (True or False) |
| barservice | Boolean | This attribute denotes whether a POI has bar service available (True or False) |
| businessmeeting | String | This attribute denotes whether a POI is fit for hosting a business meeting on a scale like the following: Poor, Average,Great |
| byo | Boolean | This attribute denotes whether a POI allows for bringing your own beverages (True or False) |
| clean | String | This attribute denotes whether a POI is considered clean on a scale like the following: Poor, Average,Great |
| coatcheck | Boolean | This attribute denotes whether a POI has coat check available (True or False) |
| cocktails | Boolean | This attribute denotes whether a POI has cocktails available (True or False) |
| crowded | String | This attribute denotes whether a POI is considered crowded on a scale like the following: Poor, Average,Great |
| datespopular | String | This attribute denotes whether a POI is considered popular to go to on dates on. This is measured on a scale like the following: Poor, Average, Great |
| delivery | Boolean | This attribute denotes whether a POI delivers food or drink (True or False) |
| dressy | String | This attribute denotes whether a POI is considered dressy on a scale like the following: Poor, Average,Great |
| drivethrough | Boolean | This attribute denotes whether a POI has a drivethrough (True or False) |
| essentialreservations | Boolean | This attribute denotes whether a POI requires reservations for attending (True or False) |
| familiespopular | String | This attribute denotes whether a POI is considered popular for families on a scale like the following: Poor, Average,Great |
| fullbar | Boolean | This attribute denotes whether a POI has a full bar available (True or False) |
| glutenfreediet | String | This attribute denotes whether a POI accommodates for a gluten free diet on a scale like the following: Poor, Average,Great |
| goodfordogs | String | This attribute denotes whether a POI is good to bring your dog to on a scale like the following: Poor, Average,Great |
| groupsonlyreservations | Boolean | This attribute denotes whether a POI requires a reservation for groups (True or False) |
| groupspopular | String | This attribute denotes whether a POI is considered popular for groups on a scale like the following: Poor, Average,Great |
| hasmusic | Boolean | This attribute denotes whether a POI has music (True or False) |
| hasparking | Boolean | This attribute denotes whether a POI has parking (True or False) |
| healthydiet | String | This attribute denotes whether a POI provides healthy options on a scale like the following: Poor, Average, Great |
| jukeboxmusic | Boolean | This attribute denotes whether a POI has a jukebox to play music (True or False) |
| latenight | String | This attribute denotes whether a POI is considered popular for late nights on a scale like the following: Poor, Average, Great |
| livemusic | Boolean | This attribute denotes whether a POI has live music (True or False) |
| noisy | String | This attribute denotes whether a POI is considered noisy on a scale like the following: Poor, Average, Great |
| onlinereservations | Boolean | This attribute denotes whether a POI offers the option to make reservations online (True or False) |
| outdoorseating | Boolean | This attribute denotes whether a POI offers outdoor seating (True or False) |
| privatelot | Boolean | This attribute denotes whether a POI has a private parking lot (True or False) |
| privateroom | Boolean | This attribute denotes whether a POI offers private rooms (for dining or parties) (True or False) |
| publiclot | Boolean | This attribute denotes whether a POI has a public parking lot (True or False) |
| quickbite | String | This attribute denotes whether a POI is considered good for a quick bite of food on a scale like the following: Poor, Average, Great |
| reservations | Boolean | This attribute denotes whether a POI offers reservations (True or False) |
| restroom | Boolean | This attribute denotes whether a POI has restrooms (True or False) |
| romantic | String | This attribute denotes whether a POI is considered good for a romantic occasion on a scale like the following: Poor, Average, Great |
| servesbarsnacks | Boolean | This attribute denotes whether a POI serves bar snacks (True or False) |
| servesbreakfast | Boolean | This attribute denotes whether a POI serves breakfast (True or False) |
| servesbrunch | Boolean | This attribute denotes whether a POI serves brunch (True or False) |
| servesdessert | Boolean | This attribute denotes whether a POI serves dessert (True or False) |
| servesdinner | Boolean | This attribute denotes whether a POI serves dinner (True or False) |
| serveshappyhour | Boolean | This attribute denotes whether a POI has a happy hour (True or False) |
| serveslunch | Boolean | This attribute denotes whether a POI serves serves lunch (True or False) |
| servestastingmenu | Boolean | This attribute denotes whether a POI has a tasting menu (True or False) |
| servicequality | String | This attribute describes the quality of service at a POI on a scale like the following: Poor, Average, Great |
| singlespopular | String | This attribute denotes whether a POI is considered popular among singles on a scale like the following: Poor, Average, Great |
| sitdowndining | Boolean | This attribute denotes whether a POI offers sit-down dining (True or False) |
| smoking | Boolean | This attribute denotes whether a POI allows smoking (True or False) |
| specialoccasion | String | This attribute denotes whether a POI is considered popular for special occasions on a scale like the following: Poor, Average, Great |
| streetparking | Boolean | This attribute denotes whether a POI offers street parking (True or False) |
| takeout | Boolean | This attribute denotes whether a POI offers takeout (True or False) |
| takesamex | Boolean | This attribute denotes whether a POI takes American Express (True or False) |
| takescreditcards | Boolean | This attribute denotes whether a POI takes credit cards (True or False) |
| takesdinersclub | Boolean | This attribute denotes whether a POI takes Diner's Club (True or False) |
| takesdiscover | Boolean | This attribute denotes whether a POI takes Discover Card (True or False) |
| takesmastercard | Boolean | This attribute denotes whether a POI takes MasterCard (True or False) |
| takesnfc | Boolean | This attribute denotes whether a POI takes NFC (phone or chipcard) payment (True or False) |
| takesunionpay | Boolean | This attribute denotes whether a POI takes UnionPay (True or False) |
| takesvisa | Boolean | This attribute denotes whether a POI takes Visa (True or False) |
| trendy | String | This attribute denotes whether a POI is considered trendy on a scale like the following: Poor, Average, Great |
| tvs | Boolean | This attribute denotes whether a POI has TVs (True or False) |
| valetparking | Boolean | This attribute denotes whether a POI offers valet parking (True or False) |
| valueformoney | String | This attribute denotes whether a POI is considered as providing good value for money spent on a scale like the following: Poor, Average, Great |
| vegandiet | String | This attribute denotes whether a POI provides vegan options on a scale like the following: Poor, Average, Great |
| vegetariandiet | String | This attribute denotes whether a POI provides vegetarian options on a scale like the following: Poor, Average, Great |
| wheelchairaccessible | Boolean | This attribute denotes whether a POI is wheelchair accessible (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) |
| wine | Boolean | This attribute denotes whether a venue offers wine (True or False) |
Data Matching
| Column Name | Type | Description |
|---|---|---|
| store_id | String | The unique ID assigned to a venue in order to differentiate it from other stores within the same chain. |
Updated 5 months ago