Submission Guidelines

This document will explain how Foursquare's Listing Syndicator partners should prepare and deliver files so that the submitted data is incorporated smoothly and accurately into Foursquare's database.

Delivery Method

​A single file containing all listings under management are to be sent to Foursquare via our sftp endpoint at ​NOTE: We will be migrating the sftp endpoint to the domain in the very near future. Thank you for bearing with us as we work through the merger of Foursquare and Factual.​

File Format

  • UTF-8 encoded, tab-delimited, flat-text file.
  • Unix line-delimiter; no carriage returns (i.e., \n rather than \r\n).
  • The file extension must be .tsv or .tab.
    • We DO NOT accept Excel files (.xls and .xlsx extensions) or files with .txt and .csv extensions.​

​File Naming Convention

The filename should follow the format specified below. Please separate each component with an underscore ("_"):

yyyymmdd: Date that the file was submitted.

contributor-name: The name of your organization.

extension: .tsv or .tab.

Additional File Naming Requirements

  • The filenames of the submissions must be consistent across every iteration of the file that is provided.
  • Do Not include any white-space, punctuation, or special characters in the filename (e.g., smiths-listings instead of Smith's Listings).
  • Only use underscores to separate the fields.
  • Only use lowercase letters.​

    Examples of Good Filenames
    ​ 20210423_data-r-us.tsv​

Examples of Bad File Names (Includes unnecessary information in the filename) 20210513_listing_syndicator.csv (underscore in middle of LS name, csv extension) (Incorrect date format and invalid LS name) (Incorrectly includes uppercase letters)
20210204_listing syndicator' (Incorrectly includes punctuation and a space) (Incorrectly includes country)​

File Updates

  • Each time you send Foursquare an updated file, we will replace the data from the previous file with the data from the updated file. Therefore, each file you send must be comprehensive, not just the diff or update.
  • Files must be refreshed at least once every 90 days.​

Data Fields

Required Fields

  • Names of the fields need to be exact, e.g., please use name, not business name or Name.
  • The ordering of the fields does not matter.​
Required AttributesNotesExample
nameBusiness name. We prefer common names over incorporated names (e.g., "Starbucks" over "Starbucks Corporation")Foursquare
addressStreet address (Not including suite number. For suite number use address_extended as noted under optional fields)1999 Avenue of the Stars
localityCity, town or equivalentLos Angeles
regionState, province, territory, or equivalent. For US states, please use the standard 2-letter abbreviated state codeCA
postcodePostcode, zipcode or equivalent90067
countryThe ISO 3166-1 alpha-2 country codeus
foreign_idThe contributor's unique ID for a record03c26917

​Optional Fields

Optional AttributesNotesExample
latitudeLatitude in decimal degrees. We prefer roof top or front door geocodes34.058695
longitudeLongitude in decimal degrees. We prefer roof top or front door geocodes-118.416792
chain_nameThe chain name associated w/ the listing, ideally matching any existing chain values in our Chains Table. Populating this field is highly recommended when you are providing complete chain dataStarbucks
neighborhoodAn array of the neighborhood(s) or other informal geography in which this entity is found["East Side", "Midtown", "Murray Hill"]
fsq_category_idsIDs of the corresponding category of the entity. Please refer to FSQ's new Category Taxonomy, released in Q2 2021[17006]
telThe primary phone number for the entity. We prefer local numbers over national or corporate numbers(310) 286-9400
websiteThe official website of the entity
store_idThe official store # of a multi-store chain1234
hoursHours of operation. Submit hours of operation as JSON (see FAQ for more info). Days should be three letter abbreviations (Mon, Tue, Wed, Thu, Fri, Sat, Sun){"mon":[["09:00", "19:00"]], "tue":[["09:00", "19:00"]], "thu":[["10:00", "18:00"]]}
twitterListing's twitter handlestaplescenter
facebook_idListing's facebook handle21466446456
instagramListing's instagram handlestaplescenterla
actionEither leave this blank or include the value closed. Please refer to Reporting Data Quality Issues section for proper usage of this fieldclosed

​For all other optional fields we can ingest, please refer to our Schema. We will also accept fields that are not listed in the schema, but they will not be visible in our datasets.​

Verified Chain Contributions

​Foursquare has created explicit associations between national and local brands and their brick-and-mortar locations. We deeply value authoritative and complete store lists that come directly from the chain or their location data representative. Accepting such complete datasets as a "verified" chain helps us accurately remove any incorrect or non-existent locations sourced from non-authority contributions.

Examples of our verified chains can be found in our Chains Table and include examples like Marriott, Starbucks, and Target. More information can be found in our doc on chains.

If you would like to submit a franchise chain to us, and your organization can provide the complete list of entities in that chain:

  • Check to see if your chain exists in our Chains table.
    • If you want to provide a chain that Foursquare is already tracking, please include a proper chain name in the filename of the inbound file. If you can only provide part of a chain, Foursquare will surface the data but won't be able to remove non-authority locations.
  • We will evaluate each chain and add it as verified if it meets our requirements:
    • Only comprehensive chains, at country level, will be used as verified chains (e.g., all Starbucks in the US, not just Starbucks in California).
    • Please include the comprehensive set of listings per chain each time you deliver your data. We will consider the most recent listings as the authoritative source for the chain.
    • Include the chain_name attribute in your delivery, populating each row of the chain w/ the associated chain name (see optional attributes above).
    • Foursquare is currently focused on major national and regional chains. Smaller chains will be evaluated, but may not necessarily be added to the Foursquare Chains table.​

Reporting Data Quality Issues

​We value all feedback on our data quality. If you discover any of the following issues in our data, please submit your feedback using the Guidelines to Report Data Quality Issues.

  • Closed business
  • Relocated business
  • Duplicated business

Data Quality Expectations for Listing Syndicators

​LS partners are trusted to provide high-quality authoritative data. As such, we relax many of our cleaning filters when processing LS data.​ The following filters are currently applied to LS data:​

  • Remove badly-encoded fields, e.g. fields with characters such as �
  • Remove emoji characters
  • Canonicalize title sigils, e.g. PhD, CPA
  • Remove corporate type abbreviations, e.g. "LLC", "Inc"
  • Remove leading and trailing punctuation/whitespace
  • Canonicalize chains, e.g. "Star bucks " → "Starbucks"
  • Filter very long names (length > 1000)
  • Reorder determiners, e.g. change "Coffee Shop, The" to "The Coffee Shop"​Because we have relaxed the cleaning process for LSs, we ask our partners to ensure their data meets our quality bar. * * The following are some guidelines on how to avoid common issues we see in low-quality inputs:​
  • Each input should represent a single business, even if two or more are co-located at the same address and/or owned by the same person.
  • The name attribute should only contain name data. Categories, telephone, web site, store id, address, etc. are encouraged in separate fields. E.g. a name field containing "Name:Starbucks; Address: 123 Main St" should be split into separate name and address fields.
  • Do not include a store id or number in the name field. E.g., "McDonald's" not "McDonald's #F1000234".
  • A good-faith effort should be made to present the name of the POI in the canonical form according to the business owner. We can coerce "Burgerking" to "Burger King" but we might have some trouble with "Home of the Whopper".
  • No HTML or markup of any kind.
  • Please don't include any special offer or other promotional information in the name (e.g., avoid "Joe's Pizza – Free Delivery").
  • Closed business inputs are encouraged, but the name field should not specify that it is closed. Instead, the action field should have a value of "closed". Example: do not submit "Starbucks — closed"; instead submit "Starbucks" in the name field and "closed" in the action field.
  • Any leading or trailing punctuation or whitespace will be removed.
  • No unbalanced parentheses or double-quotes, e.g. no "Burger King (home of the"
  • Any parentheses or quotes must be strictly part of the name. The name attribute field is not the place to include other information. See point 2.
  • We will not expand standard abbreviations. We will, however, expand proprietary abbreviations as appropriate, e.g. "KFC" → "Kentucky Fried Chicken"
  • We will not surface your data if the input language is not in country's official language. For example, Germany data has to be in German with proper accent, and the city Tübingen should be submitted as Tübingen, not Tubingen or Tuebingen.​​

Examples of Common Issues that are Cleaned

Raw DataCleaned DataReason
Atlantic Office Solutions, LLCAtlantic Office SolutionsCorporate Data
Tom Carls Insurance (All State Insurance AgentTom Carls InsuranceUnbalanced Parenthesis
UPS STORE #1352The UPS StoreChain Name Canonicalization
Locksmith ServicenullSpam Input

Foursquare LS Contribution Templates

  • The template below shows our most frequently received attributes along with some examples. Please match your column names to the names presented in the attached template and examples (case is important).

For file 20210701_contributor-name.tsv:

foreign_id  name    address address_extended    po_box  locality    region  post_town   admin_region    postcode    country tel fax latitude    longitude   website email   category_ids    hours
18f6b643-33a4-40b1-8ec6-a1c022a8d653    Fairhaven Runners & Walkers 1209 11th St            Bellingham  WA          98225   us  (360) 676-4955  (360) 676-4913  48.720504   -122.503199 [email protected]    [170]   {"wednesday":[["10:00","19:00"]],"thursday":[["10:00","19:00"]],"monday":[["10:00","19:00"]],"sunday":[["11:00","17:00"]],"saturday":[["10:00","19:00"]],"tuesday":[["10:00","19:00"]],"friday":[["10:00","19:00"]]}
1e1cbdfd-c44c-4548-a401-79aeb862a998    Western Union   470 W Madison St            Starke  FL          32091   us  (800) 325-6000      29.94379    -82.113837        [219]   {"wednesday":[["7:00","23:00"]],"thursday":[["7:00","23:00"]],"monday":[["7:00","23:00"]],"sunday":[["7:00","23:00"]],"saturday":[["7:00","23:00"]],"tuesday":[["7:00","23:00"]],"friday":[["7:00","23:00"]]}
0bc8b390-68f9-44ee-b364-047f071cc1ab    Nora's Wine Bar & Osteria   1031 S Rampart Blvd         Las Vegas   NV          89145   us  (702) 940-6672  (702) 991-2394  36.160951   -115.291507 [email protected]   [358,348]   {"wednesday":[["11:00","22:00"]],"thursday":[["11:00","22:00"]],"monday":[["11:00","22:00"]],"sunday":[["11:00","22:00"]],"saturday":[["11:00","23:00"]],"tuesday":[["11:00","22:00"]],"friday":[["11:00","23:00"]]}
bd8c41a1-489d-447e-9d00-fc3dbbd47bb1    B J's Country Store 701 E Saint Patrick St          Rapid City  SD          57701   us  (605) 341-5284      44.067367   -103.204626         [138,417]
0c82a9d0-f256-4d6e-8732-72aab6e36d0f    Alpha Swimming Pool & Spa   2600 Athena Pl          Fullerton   CA          92833   us  (714) 879-4667      33.883951   -117.970065         [260]
7a0e2e31-42cd-498f-99dd-59535f3c111f    Pueblo  34 Chapter St           London  Greater London  London  England SW1P 4NX    gb  020 7630 8895       51.49119    -0.13401            [361]
636b2bca-1607-4efb-bf31-67c149a0ac27    D B Services    57a Croydon Rd  Unit 15     Croydon Greater London  Croydon England CR0 4WQ gb  020 8253 0940   020 8253 0950   51.365812   -0.123598     [289]   {"wednesday":[["9:00","17:00"]],"thursday":[["9:00","17:00"]],"monday":[["9:00","17:00"]],"tuesday":[["9:00","17:00"]],"friday":[["9:00","17:00"]]}
32baf838-3295-45e4-a8c4-94c6ff43d8da    BEK Plastics    Sharon Rd   Unit D2     Bury St. Edmunds    Suffolk Bury Saint Edmunds  England IP33 3TZ    gb  01284 724849        52.24767    0.68819       [235]
5928e36e-4ad8-4ecb-ada8-99da86deaaae    Strathclyde Tyre Services   10-12 East Shaw St          Kilmarnock  Ayrshire    Kilmarnock  Scotland    KA1 4AJ gb  01563 544000        55.601251   -4.495676       [12]    {"wednesday":[["8:00","17:30"]],"thursday":[["8:00","17:30"]],"monday":[["8:00","17:30"]],"saturday":[["8:00","13:00"]],"tuesday":[["8:00","17:30"]],"friday":[["8:00","17:30"]]}
bec24bca-f16b-4565-9dbc-5d6b9787d1ee    Red Squrriel Tree Surgery   97 Adelaide Grove           London  Greater London  London  England W12 0JX gb  020 3509 0108       51.509046   -0.237516      [204]   {"wednesday":[["9:00","17:30"]],"thursday":[["9:00","17:30"]],"monday":[["9:00","17:30"]],"sunday":[["9:00","17:30"]],"saturday":[["9:00","17:30"]],"tuesday":[["9:00","17:30"]],"friday":[["9:00","17:30"]]}.