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 sftp.tdc.factual.com. ​NOTE: We will be migrating the sftp endpoint to the foursquare.com 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]_[contributor-name].[extension]

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
    ​20200601_listing-syndicator.tab 20200423_data-r-us.tsv​

Examples of Bad File Names
us_20200601_listing-syndicator.tab (Includes unnecessary information in the filename) 20200513_listing_syndicator.csv (underscore in middle of LS name, csv extension) 2020_foursquaredata.tab (Incorrect date format and invalid LS name) 20200204_ListingSyndicator.tab (Incorrectly includes uppercase letters)
20200204_listing syndicator's.tab (Incorrectly includes punctuation and a space) 20200204_datacontributor_mx.tab (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

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"]

fsq_category_ids

IDs of the corresponding category of the entity. Please refer to FSQ's new Category Taxonomy, released in Q2 2021

[17006]

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

http://www.foursquare.com

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 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 Data

Cleaned Data

Reason

Atlantic Office Solutions, LLC

Atlantic Office Solutions

Corporate Data

Tom Carls Insurance (All State Insurance Agent

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

For file 20190701_contributor-name.tsv:

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 http://www.fairhavenrunners.com [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  http://www.westernunion.com/        [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 http://www.noraswinebar.com [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   http://www.dbservices.co.uk     [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 http://www.bekplastics.co.uk/       [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   http://www.strathclydetyres.co.uk       [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   http://www.redsquirrelts.co.uk      [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```

 

Did this page help you?