Find all stores

Make a request to find all the store locations for a Brand in an area.

1Set up you 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.

API Key

import requests
import json

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

query = ""

req = requests.post(
    'https://api.safegraph.com/v2/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.

We are going to make a request to search for Starbucks locations in San Francisco. Since a search query returns a paginated array of places, we are going to limit the request to the first 5 results starting at the beginning.

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

SafeGraph Core Fields (more fields here)

Street Address

Returns a String for the street address of the place of interest.

City

Returns a String for the city of the point of interest.

Region

Returns a String for the state, province or county of the place of interest.

Open Hours

Returns a JSON string with days as keys and opening & closing times.

SafeGraph Geometry Fields (more fields here)

Polygon WKT

The shape of the place of interest, formatted as Well-Known Text (WKT). See polygon_wkt for more details.

Is Synthetic?

Determines if this is a precise POI footprint polygon or synthetically created from an accurate centroid and category based radius.

SafeGraph Patterns Fields (more fields here)

Visits By Day

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

import requests
import json

headers = {
    'Content-Type': 'application/json',
    'apikey': 'undefined'
}
query = """
query {
    search(filter: {
        brand: "Starbucks"
        address: {
            city: "San Francisco",
            region: "CA",
            iso_country_code: "US"
        }
    }){
        places {
            results(first: 5, after: "") {
                edges {
                    node {
                        placekey
                        safegraph_core {
								street_address
								city
								region
                        }
                        safegraph_geometry {
								polygon_wkt
								is_synthetic
                        }
                        safegraph_weekly_patterns(date: "2021-09-01") {
								visits_by_day { visits }
                        }
                    }
                }
            }
        }
    }
}
"""

req = requests.post(
    'https://api.safegraph.com/v2/graphql',
    json={
        'query': query
    },
    headers=headers
)

3Getting a response

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

{
  "data": {
    "search": {
      "places": {
        "edges": [
          {
            node: {
              "placekey": "222-222@5vg-7gr-py9",
              "safegraph_core": {
			"street_address": "1750 Divisadero St"
			"city":"San Francisco"
			"region":"CA"
              }
              "safegraph_geometry": {
			"polygon_wkt": "POLYGON ((-122.43988707661629 37.785966950304775, -122.43966110050678 37.785994507224785, -122.43964903056622 37.785939923315524, -122.43987634778023 37.78590494719715, -122.43988707661629 37.785966950304775))"
			"is_synthetic": false
              }
              "safegraph_weekly_patterns": {
			"visits_by_day": [{ "visits": 3} , { "visits": 3 }, { "visits":  2 }, { "visits": 4 }, { "visits": 4 }, {"visits": 2 }, { "visits": 2 }]
            }
            }
          },
          {
            node: {
              "placekey": "222-228@5vg-7gr-rx5",
              "safegraph_core": {
			"street_address": "2675 Geary Blvd"
			"city": "San Francisco"
			"region": "CA"
              }
              "safegraph_geometry": {
			"polygon_wkt": "POLYGON ((-122.44701838629155 37.78220987742895, -122.44697295293606 37.781855975501934, -122.44715863103858 37.781832313350186, -122.44721764266865 37.78218280134026, -122.44701838629155 37.78220987742895))"
			"is_synthetic": false
              }
              "safegraph_weekly_patterns": {
			"visits_by_day": null
              }
            }
          },
          {
            node: {
              "placekey": "222-223@5vg-7gt-7nq",
              "safegraph_core": {
			"street_address": "299 Fremont St"
			"city": "San Francisco"
			"region": "CA"
              }
              "safegraph_geometry": {
			"polygon_wkt": "POLYGON ((-122.39331353499995 37.788969672000064, -122.393114906 37.788809797000056, -122.39309720799997 37.78882311500007, -122.39296979399995 37.78872154100003, -122.39314983199995 37.78858604800007, -122.39339072299998 37.78877993900005, -122.39342568699999 37.78875362500003, -122.39345104299997 37.788774035000074, -122.39366082999999 37.78861615200003, -122.39360166299997 37.78856853100007, -122.393579811 37.78858497700003, -122.39352909699994 37.788544158000036, -122.39336301699996 37.788669147000064, -122.39318974499997 37.78852968100006, -122.39338641999996 37.78838166700007, -122.39337374099995 37.78837146300003, -122.39362723099998 37.78818068800007, -122.39396532299997 37.78845281500003, -122.39375116699995 37.788613988000066, -122.39376807099995 37.78862759400005, -122.39354517499999 37.78879534400005, -122.39349445999994 37.78875452500006, -122.39341578999995 37.78881373000007, -122.39346650399995 37.788854549000064, -122.39331353499995 37.788969672000064))"
			"is_synthetic": false
              }
              "safegraph_weekly_patterns": {
			"visits_by_day": [{ "visits": 4 }, { "visits": 2 }, { "visits": 6 }, { "visits": 3 }, { "visits": 6 }, { "visits": 14 }, { "visits": 19 }]
              }
            }
          },
          {
            node: {
              "placekey": "222-224@5vg-7gr-6kz",
              "safegraph_core": {
			"street_address": "2020 Market St"
			"city": "San Francisco"
			"region": "CA"
              }
              "safegraph_geometry": {
			"polygon_wkt": "POLYGON ((-122.4276615679264 37.769093827157405, -122.42764413356781 37.76898251408742, -122.42784395813942 37.7689782735862, -122.42785066366196 37.76908746641506, -122.4276615679264 37.769093827157405))"
			"is_synthetic": false
              }
              "safegraph_weekly_patterns": {
			"visits_by_day": null
              }
            }
          },
          {
            node: {
              "placekey": "222-224@5vg-7h2-6c5",
              "safegraph_core": {
			"street_address": "1700 Owens St"
			"city": "San Francisco"
			"region": "CA"
              }
              "safegraph_geometry": {
			"polygon_wkt": ""POLYGON ((-122.39379733800888 37.76720784308407, -122.39368870854378 37.767133102420864, -122.39384427666664 37.767013835248655, -122.3939448595047 37.767087515879965, -122.39379733800888 37.76720784308407))""
			"is_synthetic": false
              }
              "safegraph_weekly_patterns": {
			"visits_by_day": null
              }
            }
          }
        ]
      }

    }

  },
  "extensions": {
    "row_count": 10,
    "version_date": "1638259204__2021_11"
  }
}

4Parsing the data

Since the response is a JSON object, you can select the data object and select the response for the search array.

r_json = req.json()
edges = r_json['data']['search']['places']['results']['edges']

print(json.dumps(edges, indent=4, sort_keys=True))