Base Attributes

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.

Contents

Helpful Links

Column Definitions: Base Attributes

placekey

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.

parent_placekey

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

location_name

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 concatonated with the way the stop is identified.

safegraph_brand_ids, brands

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.

top_category, sub_category, naics_code

top_category and 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.

latitude , longitude

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

street_address

  • We implement a number of steps to clean, validate and standardize street_address.
  • You should expect street_address to 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.
    • primary_number
    • street_predirection
    • street_name
    • street_postdirection
    • street_suffix

city

  • In the US, all centroids (latitudes/longitudes) are referenced against a geospatial file of city boundaries as defined by the US Census Bureau (browse the boundaries here). In edge cases, the preferred city name in the address line reflects a pre-annexed city name, and we try our best to preserve those city names where possible.

  • 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 region is populated. The region column in Great Britain refers to county boundaries, and counties are a decent alternative to cities for geographic filtering.

  • city may be null for POIs outside of the US and Canada as well as for National Park POIs in the U.S.

region

  • When iso_country_code == US, then this is the US state or territory.
  • When iso_country_code == CA, then this is the Canadian Province or territory.
  • When iso_country_code == GB, then this is the United Kingdom county.
  • For all other iso_country_codes this is the state/province or equivalent.

postal_code

  • When iso_country_code == US, then this is the US 5 digit zip code.
  • When iso_country_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).
  • When iso_country_code == GB, then this is the British postal code. Learn more about Great Britain postal code precision here.
  • postal_code may be null for National Park POIs in the U.S.

Key Concepts

Placekey

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.

Point POIs

Some places are small and not well defined by a geometric shape. We refer to these places as "Point POIs" and intentionally do not offer a polygon nor Patterns data. Places like transit stops, ATMs, kiosks, and electric vehicle charging stations are examples of Point POIs found in our data, and we flag these by setting the geometry_type column = "POINT." Point POIs are a premium portion of the Places offering, and we are continually adding new types and brands.

Brands

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 brands and 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 safegraph_brand_id.

Every place has a location_name, but only POIs belonging to a chain will have a brand. In some cases, location_name and 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:

  • 72 is the general category Accommodation and Food Services.
  • 722 is the more specific category Food Services and Drinking Places.
  • 7225 is the even more specific category Restaurants and Other Eating Places.
  • 722513 is 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.


Did this page help you?