Flat File 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 (see definition in Glossary) . 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
    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 NameTypeDescription
    popularityStringMeasure 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_bucketStringThis 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_ratingStringThis 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_closedDateThe 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 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)

    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.

    Sign In