Data Quality Expectations
Filters We Apply
The following filters may be applied to the data we receive:
- 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".
Content Expectations
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.
- Places should represent brick-and-mortar locations with an address and lat/lng which are useful for locating the place. We prefer you do not include listings for businesses which only operate online and have no physical presence and will attempt to identify and filter out such locations if necessary.
- 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 closed field should be set to true. Example: do not submit "Starbucks — closed"; instead submit "Starbucks" in the name field and true in the closed 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 may, however, expand proprietary abbreviations as appropriate, e.g. "KFC" → "Kentucky Fried Chicken".
Chain Contributions
Foursquare has created explicit associations between national and local brands and their brick-and-mortar locations. To provide chain data, indicate in the foreign_chain_id field the stable identifier you use for that chain so that we can link it to a chain within our taxonomy. This should preferably be an actual id and not simply the name of the chain, to ensure that it does not change over time.
Curated Chains
We deeply value authoritative and complete store lists that come directly from the chain or their location data representative. Accepting such complete datasets as "curated" chains helps us accurately remove any incorrect or non-existent locations sourced from non-authority contributions. 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 will only add it as curated if it meets our requirements:
- Only comprehensive chains, at country level, will be used as curated 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.
- Make sure foreign_chain_id is populated for each listing in the chain and that the identifier is stable from delivery to delivery.
- Extraneous locations are not included in the chain (e.g. a chain's headquarters, or a service offered at a location in a chain).
- Names for places within the chain are suitably formatted in cases where the names are not homogeneous (e.g. if your internal chain id is the same for Chili's and Chili's To Go locations, they should still be able to be differentiated based on their names).
In certain cases we may already have an authoritative store list for that chain and may prefer that data in cases where there are discrepancies.
After Your Data Is Ingested
After the data you deliver is incorporated into our Places Engine, it is part of our Open Source Places data product and is subject to human moderation and updates. We make no guarantee that the data will be immediately updated to reflect the changes in the file delivery, and if those changes are applied and reflected within our dataset, they are still subject to change as we obtain new information.