Data Schema

Foursquare’s Places Flat File comes with 25 core attributes and a multitude of rich attributes. The Core Attributes are included in all of our packages. Each rich attributes package can be licensed at an additional charge (please speak to your Foursquare representative for more information). Packages are available in a TSV format.

See below for details of what is offered.

Places Schema

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
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
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 of the most granular category (or categories) available for this POI. See our Categories page for more details
fsq_category_labels Array(Arrays) Label 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)

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
email String Primary contact email address of organization, if available
facebook_id String This POI's Facebook ID, if available
instagram String This POI's Instagram handle, if available
twitter 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

provenance_rating

String

Rating to indicate the authoritativeness of sources for each POI. Values range from 1, indicating venue data is acquired directly from business owner, its official website or its location data representative, to 4, indicating venue data is sourced exclusively from open web crawls

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

closed_bucket

String

Probability that a POI is closed.

  • VeryLikelyClosed: indicates places with probabilities greater than 90% being closed
  • LikelyClosed indicates places with probabilities 70–90% being closed
  • Unsure indicates places w/ probabilities less than 70% closed or open
  • LikelyOpen indicates places with probabilities 70–90% being open
    VeryLikelyOpen: indicates places with probabilities greater than 90% being open

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 aPOI 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)

Did this page help you?