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
- File Format
- File Naming Convention
- File Updates
- Data Fields
- Verified Chain Contributions
- Reporting Data Quality Issues
- Data Quality Expectations for Listing Syndicators
- Foursquare LS Contribution Templates
- FAQ
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: 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
20210601_listing-syndicator.tab 20210423_data-r-us.tsv
Examples of Bad File Names
us_20210601_listing-syndicator.tab
(Includes unnecessary information in the filename) 20210513_listing_syndicator.csv
(underscore in middle of LS name, csv extension) 2021_foursquaredata.tab
(Incorrect date format and invalid LS name) 20210204_ListingSyndicator.tab
(Incorrectly includes uppercase letters)
20210204_listing syndicator's.tab
(Incorrectly includes punctuation and a space) 20210204_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"]]} |
Listing's twitter handle | staplescenter | |
facebook_id | Listing's facebook handle | 21466446456 |
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 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 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"]]}.
Updated about 1 month ago