Learn more about your visitors

Find out who is visiting and when they are coming.

1Set up your SafeGraph account

Create or log in to your SafeGraph account and create your API Key.

Now, lets include your API key in the request. Copy your API key and paste it below.

import requests

headers = {
    'Content-Type': 'application/json',
    'apikey': 'undefined'
}

query = ""

req = requests.post(
    'https://api.safegraph.com/v1/graphql',
    json={ 'query': query },
    headers=headers
)
2Setting up your query

The Places API allows you to specify the exact data you want. This means that you can ask for data from Core, Geometry, or Patterns for any location. In this example we are going to be focused around our Weekly Patterns data.

We are going to make a request to lookup a Starbucks location at 1390 Market St, San Francisco, CA.

Select a few of the fields below for the data you want to include in the response.

SafeGraph Weekly Patterns (more fields here)

SafeGraph Patterns Fields

The number of visits to the POI each day (local time) over the covered time period.

The number of visitors to the POI from each census block group or dissemination area based on the visitor's home location.

Median distance from home travelled by visitors (of visitors whose home we have identified) in meters.

import requests

headers = {
    'Content-Type': 'application/json',
    'apikey': 'undefined'
}
query = """
query {
    lookup(query: {
        location_name: "Starbucks"
        street_address: "1390 Market St"
        city: "San Francisco"
        region:"CA"
        iso_country_code:"US"
    }) {
        placekey
        weekly_patterns(start_date: "2021-07-18" end_date: "2021-07-24") {
			visits_by_day{ visits }
			visitor_home_cbgs
			visits_by_each_hour { visits }
        }
    }
}
"""

req = requests.post(
    'https://api.safegraph.com/v1/graphql',
    json={
        'query': query
    },
    headers=headers
)
3Getting a response

After you send the request, you will receive a response that will reflect the fields you included in the query.

{
    "data": {
        "lookup": {
            "placekey": "zzy-222@5vg-7gq-7qz",

            "weekly_patterns": {
				"visits_by_day": [
					{
						"visits": 3 
					},
					{
						"visits": 2 
					},
					{
						"visits": 1
					},
					{
						"visits": 1
					},
					{
						"visits": 1
					},
					{
						"visits": 1
					},
					{
						"visits": 0
					}
				],
				"visitor_home_cbgs": { 
					"061130107041": 4 
				}
				"visits_by_each_hour": [
					{
						"visits": 0 
					},
					{
						"visits": 0 
					},
					{
						"visits": 0
					},
					{
						"visits": 0
					},
					{
						"visits": 0
					},
					{
						"visits": 0
					},
					{
						"visits": 0
					},
					{
						"visits": 0
					},
					{
						"visits": 0
					},
					{
						"visits": 0
					},
					{
						"visits": 1
					},
					# {...} 
				]
            }
        }
    },
    "extensions": {
      "row_count": 1,
      "version_date": [
        "safegraph_core: 1643356807__2022_01",
        "safegraph_geometry: 1643356807__2022_01",
        "safegraph_weekly_patterns2: 2022_01_11",
        "safegraph_monthly_patterns: 2022_01_11"
      ]
    }
}

4Parsing the data
Since the response is a JSON object, you can select the data lookup object and pull the fields you need.
r_json = req.json()
print(r_json['data']['lookup'])

How many people visited this location?

data.lookup.safegraph_weekly_patterns.visits_by_day

Where are people coming from?

data.lookup.safegraph_weekly_patterns.visitor_home_cbgs

When are they visiting?

data.lookup.safegraph_weekly_patterns.visits_by_each_hour