Release Notes: 2018-09-28

Our September 28th release includes two major changes:

1. Brand information file location and schema changes
2. enclosed_geometry_mapping has been replaced with polygon_class

Please contact your Customer Success Manager if you have any questions or issues with the schema migration process.

Brand information file and schema change (breaking change)

• Additional information about brands was formerly housed in files in a directory called /brand_mappings, and is now housed under /brand_info.
• The schema of this additional information has changed: see schema docs for more.
• Most importantly, we have introduced safegraph_brand_id in this release. safegraph_brand_id will remain consistent over time, but brand_name may not. Please use safegraph_brand_id from now on to search and filter SafeGraph Places.
• To map between brand names and safegraph_brand_id, see the following sheet:

Why did some of the old-brand-names not get successfully mapped to new_brand_name? Look for rows with NA in the new_brand_name column. For instance, napa auto parts did not get mapped to a new name.

We changed the criteria for us to consider an entity to be a brand. We dropped a few brands that we felt did not meet these criteria. We are working towards increasing the number of brands. If there are any that are important for your use case that got dropped -- please let your Customer Success Manager know.

Is there a reason some of the new_brand_name values are all lower case (walmart, ampm, starbucks)?

Most of the new_brand_name values have capital letters at the start of each word. But then some are all upper case like SUBWAY.

Should we use safegraph_brand_id from now on? What should we use the brand name for instead?

Yes, you should use safegraph_brand_id wherever possible. This is because brand_name may not actually be unique. Below are two brands entitled Bealls that refer to different entities:

1. Bealls (Florida)
2. Bealls (Texas)

Even names that are unique to a single business might change over time. Therefore, it is advisable to rely on safegraph_brand_id instead to search and filter for a specific entity.

Brand names can be used to display the human-readable name associated with a brand.

Replacing enclosed_geometry_mappings with polygon_class (breaking change)

• In prior versions of SafeGraph Places, /enclosed_geometry_mappings had 3 columns and ~930K records (one for each of the ~930K POI that had a parent_safegraph_place_id i.e. POI that are enclosed inside of other POI):
  • safegraph_place_id: the safegraph_place_id of the POI
  • is_place_centroid: how accurate is the centroid associated with this POI. true = we believe this centroid describes the POI itself. false = the centroid describes the parent structure, not this POI itself
  • is_place_polygon: how accurate is the polygon associated with this POI. true = we believe this polygon describes the POI itself. false = the polygon describes the parent structure, not this POI itself
  • This release of SafeGraph Places removes enclosed_geometry_mappings files.
    • Our centroids always attempt to describe the POI itself, and not the parent (enclosing) structure -- and therefore the is_place_centroid field is no longer necessary (i.e. this is always true).
    • Sometimes, we may still be unsure of the polygon for a specific POI. This happens most often in dense urban environments, airports or shopping malls, where many POI may share a single building. In this case, we will assign the enclosing / parent structure's polygon to the POI.
    • polygon_class is a new field in the main /poi/ files that identifies whether the polygon describes this specific POI. Some examples are referenced below:

1. Single POI with a polygon where polygon_class = OWN

2. Multiple POI sharing the same polygon, with none of the POI being the parent entity, In this case, two POI (Liholiho Yacht Club and Louie's Gen Gen Room) are located in the same building. Neither POI contains the other (as opposed to the example below). Therefore, polygon_class = SHARED for both of these POI.

3. Multiple POI sharing the same polygon, however, one POI is the parent / enclosing entity of the others. This example shows a mall named Carolina Place. Inside the mall, there are POI such as Cafe of the Carolinas and Build a Bear Workshop. All of these POI have the same polygon because we are not sure of the exact polygons for POI inside the mall. Therefore, Carolina Place (the enclosing mall) will include polygon_class = OWN and Build a Bear Workshop (an enclosed POI) will include polygon_class = SHARED.

Changelog

• broken: Brand information: location of files and schema has changed (see above for detail).
• broken: Enclosed_geometry_mappings removed. Use new field polygon_class to identify whether a polygon describes a POI specifically (see above for detail).
• added: phone_number field has been added.