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 20200423_data-r-us.tsv

Examples of Bad File Names (Includes unnecessary information in the filename) 20200513_listing_syndicator.csv (underscore in middle of LS name, csv extension) (Incorrect date format and invalid LS name) (Incorrectly includes uppercase letters) 20200204_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 Attributes Notes Example
name Business name. We prefer common names over incorporated names (e.g., "Starbucks" over "Starbucks Corporation"). Foursquare
address Street address (Not including suite number. For suite number use address_extended as noted under optional fields) 1999 Avenue of the Stars
locality City, town or equivalent Los Angeles
region State, province, territory, or equivalent. For US states, please use the standard 2-letter abbreviated state code. CA
postcode Postcode, zipcode or equivalent. 90067
country The ISO 3166-1 alpha-2 country code us
foreign_id The contributor's unique ID for a record 03c26917

Optional Fields

Optional Attributes of Note Notes Example
latitude Latitude in decimal degrees. We prefer roof top or front door geocodes. 34.058695
longitude Longitude in decimal degrees. We prefer roof top or front door geocodes. -118.416792
chain_name The 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 data. Starbucks
neighborhood An array of the neighborhood(s) or other informal geography in which this entity is found ["East Side", "Midtown", "Murray Hill"]
category_ids IDs of the corresponding category of the entity. Please continue to use Factual's Place Categories for the time being. [210]
tel The primary phone number for the entity. We prefer local numbers over national or corporate numbers. (310) 286-9400
website The official website of the entity.
store_id The official store # of a multi-store chain. 1234
hours Hours 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"]]}
twitter Listing's twitter handle. staplescenter
facebook_id Listing's facebook handle. 21466446456
instagram Listing's instagram handle. staplescenterla
action Either leave this blank or include the value closed. Please refer to Reporting Data Quality Issues section for proper usage of this field. closed

​ For all other optional fields we can ingest, please refer to our core attributes and extended-attributes. 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 Data Cleaned Data Reason
Atlantic Office Solutions, LLC Atlantic Office Solutions Corporate Data
Tom Carls Insurance (All State Insurance Agen Tom Carls Insurance Unbalanced Parenthesis
UPS STORE #1352 The UPS Store Chain Name Canonicalization
Locksmith Service null Spam 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). Collapse

For file 20190701_contributor-name.tsv:

factual_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    [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   [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"]]}
  • Here is an example of the data quality issues template:

For file 20190301_contributor-name_FLAGS.tsv:

action  preferred_id    flagged_id  country
duplicate   26a158ac-df89-4f86-8043-93c011f9b7a7    226bfd2f-2558-44fd-874c-bc6035f2e9a0    us
duplicate   c7aa4b6d-8d4e-47a8-83f9-7b8a5ab132c2    552edbc0-3591-438b-a0f3-fa8459abbf75    ca

If you have any further questions, please reach out to us at:

Next Steps

Reporting Data Quality Issues

Frequency Asked Questions