The SafeGraph Developer Hub

Welcome to the SafeGraph developer hub. You'll find comprehensive guides and documentation to help you start working with SafeGraph as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Matching Service Overview

Seamlessly integrate your existing POI data with SafeGraph's enriched Places data.

How It Works

  • You provide SafeGraph your existing POI data with all the data you have about a place. See Matching Data Format below for instructions on how to format your POI data.
  • SafeGraph will process your data to identify which places exist today and all the data SafeGraph knows about a given place.
  • For any of the places that determined to exist, SafeGraph will return the safegraph_place_id for each place provided to join your existing dataset with any Places or Places Patterns data.
  • SafeGraph will also provide a report of the:
    • 1) number of places matched
    • 2) number of places that do not exist (bad data, closed location, etc.)

Matching Data Format

In order to use the matching service:

  • Please provide us with a CSV of your POI data.
  • Column headers are required.
  • Please include all columns you have along with descriptive headers.
  • To the extent your columns overlap with any of the columns in our Places Schema, please use our Column Name for the header. Please also use the preferred Data Type specified in our Places Schema.
  • If you are having issues converting your column to the specified Data Type, it is better to still send the column. Do not delete the data. Despite format, we might still be able to use the data to increase the match rate.
  • The more data the better so if you have additional columns not listed below, please include them along with descriptive headers for each additional column.
  • It is not necessary that you have all fields in the sample. Please send what you have -- the more fields the better to improve the match rate. However, note that our service is quite reliant on the name and address columns currently. So, matching rate will be significantly impacted if those fields are missing.

Example Match

If you provide the following information about a place:

Column Name Value
customer_place_id 12345
location_name Land’s End
street_address 123 main street
city lancaster
state pa
zip_code 17601
latitude 40.068711
longitude -76.337538

SafeGraph will return the safegraph_place_id mapped to your own place ID:

Column Name Value
customer_place_id 12345
safegraph_place_id sg:8d8f2d4210044741988f0481996733b6

This mapping can then be used to integrate any Places or Places Patterns data you decide to purchase. In this example, you would be able to integrate the following attributes:

Column Name Value
customer_place_id 12345
safegraph_place_id sg:8d8f2d4210044741988f0481996733b6
parent_safegraph_place_id sg:20581e265fbc45d98c4081155f8e6389
safegraph_brand_ids SG_BRAND_ffa549d5128e982f0e10e2a236048c5f
location_name Land's End
brands Land's End
top_category Clothing Stores
subcategory Family Clothing Stores
naics_code 448140
latitude 40.068711
longitude -76.337538
street_address 200 park city center
city lancaster
state pa
zip_code 17601
open_hours [6360,7020,7800,8460,9240,9900,660,1080,2040,2700,3480,4140,4920,5580]
phone_number 17172955805
polygon_wkt POLYGON ((-76.33729666215422 40.0687062, -76.3373081363591 40.06865053831385, -76.33734143579863 40.06860032518135, -76.33743008413396 40.06859937452737, ... , ... , -76.33729666215422 40.0687062))
polygon_class OWNED_POLYGON
raw_visitor_counts 179
raw_visit_counts 209
distance_from_home 16605
minimum_dwell 21
popularity_by_day {"Monday":31,"Tuesday":25,"Wednesday":21,"Thursday":22,"Friday":19,"Saturday":61,"Sunday":30}
popularity_by_hour [1,1,1,1,1,1,2,6,6,9,21,31,37,42,52,37,50,41,27,12,11,6,0,1]
extraordinary_same_day_brand {"BJ's Wholesale Club":25,"Olive Garden":25,"Burger King US":16,"Sears":14,"Chili's Grill & Bar":14, ...}
extraordinay_same_month_brand {"Sheetz":42,"mcdonalds":32,"walmart":28,"CVS":20,"Dollar Tree":19,"Giant Food Stores":19,"Sunoco":19,"Target":18, ...}

In this example, you would also be able to associate your existing POI with the parent POI as the Land's End is located within the Park City Center mall:

Column Name Value
safegraph_place_id sg:20581e265fbc45d98c4081155f8e6389
location_name Park City Center
top_category Lessors of Real Estate
subcategory Malls
naics_code 531120
latitude 40.067207
longitude -76.339737
street_address 142 park city center
city lancaster
state pa
zip_code 17601
open_hours [6360,7020,7800,8460,9240,9900,660,1080,2040,2700,3480,4140,4920,5580]
phone_number null
polygon_wkt POLYGON ((-76.34575295555845 40.06553036258317, -76.34551057463136 40.066298389486775, -76.3450107016389 40.06707461841828, -76.34364813945933 40.06682829738607, ... , ... , -76.34575295555845 40.06553036258317))
polygon_class OWNED_POLYGON

Matching Service Overview


Seamlessly integrate your existing POI data with SafeGraph's enriched Places data.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.