The Base Attributes of our Places data provide the fundamental details about a POI. This includes location name, address, lat/long, category, brand, and more. See below for additional detail on each column.
- Column Definitions for definitions and in depth details
- Key Concepts relevant to our Places data
Column Definitions: Base Attributes
Placekey is a unique and persistent identifier for any physical place in the US that intelligently partitions the ID into meaningful encodings. See the Placekey key concept for a detailed description.
This Placekey column will identify a larger place that may encompass a given POI, which we refer to as the "Parent". Think of an indoor shopping mall as the parent of the individual stores inside. For any place without an assigned polygon, the
parent_placekey column will be null because we rely on geometric relationships to identify parent/child hierarchy. So for example, any of our Point POI will not have an assigned parent because they do not have defined polygons. You can find out more about our process for defining these relationships in our Spatial Hierarchy section where we also include a list of all the types of places that can serve as "Parents".
The best name that can be given to the POI. This will most likely align to those business names shown on the front door (as opposed to legal entity names). For less obvious locations (like bus stops) the
location_name will display the most descriptive string possible like the name of the operator concatenated with the way the stop is identified.
These columns reflect the "brand" or "brands" that we associate with a given POI (and their corresponding ID we've assigned them). See our Brands Section for additional details on what we consider a brand and how we maintain them.
sub_category are the string labels associated with the first 4 digits and 6 digits of
naics_code, respectively. See Categorization of POI section above.
- In general, latitude and longitude are defined by our best knowledge of the POI location. It is not designed to specifically locate the front door of the business, but rather defines the general center of the business.
- Latitude and longitude still attempt to identify the individual business even if that business and others have the same polygon (e.g. strip mall).
- We implement a number of steps to clean, validate and standardize
- You should expect
street_addressto be title-cased, consistent, and friendly for human reading. Please send us your feedback if you see otherwise.
- If you care about street addresses as much as we do, we also have more specific address columns to split out address components. These are optional and available upon request for future deliveries.
In the US, city names are the output of normalized address strings from POI sources. There is no widely adopted standard for US cities, so we try our best to provide an alternative city name for each US POI in
alt_address.cityin our address attributes schema. We use the US Census Bureaus' designated places boundaries to encode an alternative city name when different from the POI source. We do this by spatially joining all US POI centroids (latitudes/longitudes) against this boundary file.
In Canada, city names are the output of normalized address strings from POI sources.
In Great Britain, city names are the output of normalized address strings from POI sources, but in edge cases, we allow POIs to have a null city name as long as
regionis populated. The
regioncolumn in Great Britain refers to county boundaries, and counties are a decent alternative to cities for geographic filtering.
citymay be null for POIs outside of the US and Canada as well as for National Park POIs in the U.S.
Starting in February 2023,
regionin Places will align with OpenStreetMap’s (OSM) understanding of global administrative boundaries. OSM utilizes a numerical hierarchy to describe geographical entities. These are denoted by the tag admin_level and a corresponding value (read more here).
This system helps ensure a consistent understanding of a geographical unit across countries and is a widely accepted standard in the spatial data community.
regionin Places should match closely with how regions are understood for each country (e.g., prefectures in Japan).
We recommend comparing
regionvalues to OSM admin_levels 3-6 and believe that admin_level = 4 is generally the best fit for most countries.
For all countries,
iso_country_codewill be equivalent to admin_level = 2.
US, then this is the US 5 digit zip code.
CA, then this is the Canadian postal code in the form of a 3 digit Forward Sortation Area (FSA), a space, and the 3 digit Local Delivery Unit (LDU).
GB, then this is the British postal code. Learn more about Great Britain postal code precision here.
postal_codemay be null for National Park POIs in the U.S.
census_codeshows the ID of a statistical area created and maintained by a country's census bureau for population and demographic reporting. In most countries, the census bureau collects data across many levels of granularity.
- Ex: In the U.S., the census bureau reports data at the country, state, county, census tract, census block group, and census block level).
- We always encode the ID of the most granular unit where a country's census bureau collects and reports common population/demographic statistics.
census_codecan then be leveraged as a join key into open census datasets (like SafeGraph's Open Census Data in the US) to enrich Places with key demographic insights.
US, then the
census_code is a "FIPs" (Federal Information Processing) code which is a hierarchical ID that denotes the following areas in descending levels of granularity: state, county, census tract, and census block group.
Example FIPS code: 012345678901
- 01 = state
- 01234 = county
- 01234567890 = census tract
- 012345678901 = census block group
That's four keys in one ID! 🎉 Census Block Groups (CBGs) are the second smallest geographical unit of analysis maintained by the US Census Bureau, and the smallest unit of analysis used for demographic reporting. A typical CBG contains ~2000-7500 residents.
CA, then the
census_code is a dissemination area.
- Dissemination areas are the smallest unit of analysis used for demographic reporting in Canada.
census_code is currently null where
Placekey is a unique and persistent identifier for any physical place in the world that intelligently partitions the ID into meaningful encodings. So how does Placekey work?
When both parts of a placekey come together, the final result reads as [email protected] This is a unique way of shedding light on both the descriptive element of a place as well as its geospatial position in the physical world via a single identifier.
What: Address Encoding
The first three characters refer to the Address Encoding, creating a unique identifier for a given address. An address at “555 Main Street Suite 105” will have a different Address Encoding than “555 Main Street Suite 106.” However, "444 Second Street, Suite 4" will have the same address encoding as "444 2nd St. #4" to adjust for common address formats.
What: POI Encoding
The second set of three characters in the 'What Part' refers to the POI Encoding. If a specific place has a location name (like "Central Park") and is already included in the Placekey reference datasets, these characters will be present. The benefit of the POI Encoding is that it can point to a specific point of interest that may have existed at a certain address at a given point in time.
Where: H3 Encoding
The 'Where Part,' on the other hand, is made up of three unique character sequences, built upon Uber’s open source H3 grid system. This information in the 'Where Part' is based on the centroid of that place. In other words, we take the latitude and longitude of a specific place and then use a conversion function to determine a hexagon in the physical world, representing about 15,000 sq. meters, containing the centroid of that place. The 'Where Part' of the Placekey is, therefore, the full encoding of that hexagon.
Open access to your own datasets using the FREE Placekey API.
SafeGraph curates thousands of distinct brands with more added every month. These are chains of commercial POIs that represent major brands around the world (McDonald's, AMC, Macy's, Chevrolet, Whole Foods Market, etc.).
Note that ~80% of POIs have no brand associated as they are single commercial locations (local restaurants, museums, etc.). SafeGraph is continually improving the fill rate of brands with each release - please contact us if you notice a missing brand.
Some POIs include multiple brands. For example, a car dealership may sell multiple car brands, or branded POIs may be co-located (Ex: Taco Bell and KFC in the same space; IMAX and AMC cinemas in the same building). In these cases, the
safegraph_brand_ids are listed as an array that is alphabetized by brand name (the order does not specify any importance).
Brands provide an easy way to isolate major stores. If you know you are searching for a brand that we cover, we advise searching by the
brands column instead of the
location_name column. For even better specificity, search the brand_info file by
brands and build your workflows around
Every place has a
location_name, but only POIs belonging to a chain will have a
brand. In some cases,
brand will be the same, but in other cases they are intentionally different. For example, the most common name for an individual Starbucks store is its brand name, so it is also reflected in the
location_name column. However, the most common name for the Bellagio Hotel & Casino is not its brand name "MGM Resorts." In this case, the
location_name shows "Bellagio Hotel & Casino" and
brands shows "MGM Resorts."
Categorization of POI
SafeGraph Places uses the North American Industry Classification System (NAICS) developed by the US Census Bureau, which consists of a numeric NAICS code up to 6 digits in length. Although this taxonomy was developed in the US, we have found it just as useful for categorizing POIs in other countries as well and will continue to use it until a better alternative presents itself. We currently reference the 2017 version of NAICS. We will provide an update if and when we ultimately update to reflect the 2022 changes.
The NAICS code itself is hierarchical; in other words, the first 2 digits describe a very general category, and additional digits describe more and more specific categories. For example:
72is the general category
Accommodation and Food Services.
722is the more specific category
Food Services and Drinking Places.
7225is the even more specific category
Restaurants and Other Eating Places.
722513is the most specific category
Limited-Service Restaurants(i.e. quick-serve or fast-food restaurants).
We strive to assign a best fitting
naics_code for all of our POIs. Our goal is to assign a full six digits for maximum granularity wherever possible, but our category algorithm cannot always infer a high confidence six digit
naics_code based on POI name and other descriptive metadata. In these cases, we provide a shorter
naics_code where we do have high confidence in the assignment (i.e. 3, 4 , 5 digits). In these circumstances, we choose to sacrifice the extra digits of precision in exchange for high veracity predictions and also because the extra precision is not always meaningfully different (i.e. some adjacent 6 digit NAICS are extremely similar).
See our Places Summary Statistics for the latest details on counts and coverage.
Also see our use of Category Tags to provide more flexibility and granularity where the NAICS code classification falls short.
Updated about 2 months ago