Once you've got a feel for the query format and output, transition over to your API tool of choice. Make sure to point to the Places API URL. We've provided a few examples below to quickly kick things off in some common languages.

API Endpoint

https://api.safegraph.com/v2/graphql

Sample Requests

📘

{your-api-key}

Remember to input your unique API key where {your-api-key} is denoted in the below samples.

Get Core Info on a Specific Starbucks
Submitting the individual placekey with the Lookup query. This is the same query as the original one used in the above GraphiQL Explorer.

query {
  lookup(placekey: "[email protected]") {
    placekey
    safegraph_core {
      location_name
      street_address
      city
      region
      postal_code
      iso_country_code
    }
  }
}
curl --location --request POST 'https://api.safegraph.com/v2/graphql' \
--header 'apikey: {your-api-key}' \
--header 'content-type: application/json' \
--data-raw '{"query":"query {\r\n  lookup(placekey: \"[email protected]\") { \r\n\tplacekey \r\n    safegraph_core {\r\n      location_name\r\n      street_address\r\n\t  city\r\n      region\r\n      postal_code\r\n      iso_country_code\r\n    }\r\n  }\r\n}","variables":{}}'
# pip install safegraphQL
import safegraphql.client as sgql

sgql_client = sgql.HTTP_Client(apikey = '{your-api-key}')

pk = '[email protected]'
cols = [
    'location_name',
    'street_address',
    'city',
    'region',
    'postal_code',
    'iso_country_code'
]

sgql_client.lookup(product = 'core', placekeys = pk, columns = cols)
import os
import requests
import json

headers = {
    'Content-Type': 'application/json',
    'apikey': '{your-api-key}'
}

query = """
query {
  lookup(placekey: "[email protected]") {
    placekey
    safegraph_core {
      location_name
      street_address
      city
      region
      postal_code
      iso_country_code
    }
  }
}
"""

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

r_json = req.json()
print (json.dumps(r_json, indent=4, sort_keys=True))
{
  "data": {
    "lookup": {
      "placekey": "[email protected]",
      "safegraph_core": {
        "location_name": "Starbucks",
        "street_address": "2020 Market St",
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94114",
        "iso_country_code": "US"
      }
    }
  },
  "extensions": {
    "row_count": 1,
    "version_date": "1627739802__2021_07"
  }
}

Search For Geometry Data On Starbucks in Denver, CO
Search query using brand and address fields. Note this search is limited to 5 responses per the first argument. To filter through a longer list, you'd need to expand that limit and ultimately paginate through the responses using the after argument.

query{
  search(first: 5 filter:{
    brand:"Starbucks"
    address: {
      city:"Denver"
      region: "CO"
    }
  }) {
    places {
      edges {
        node {
          placekey
          safegraph_geometry{
            location_name
            street_address
            polygon_wkt
            polygon_class
            includes_parking_lot
            is_synthetic
          }
        }
      }
    }
  }
}
curl --location --request POST 'https://api.safegraph.com/v1/graphql' \
--header 'apikey: {your-api-key}' \
--header 'content-type: application/json' \
--data-raw '{"query":"query{\n  search( first:5 filter:{\n    brand:\"Starbucks\"\n    address: {\n      city:\"Denver\"\n      region: \"CO\"\n    }\n  }) {\n    placekey\n    safegraph_geometry{\n      location_name\n      street_address\n      polygon_wkt\n      polygon_class\n      includes_parking_lot\n      is_synthetic\n    }\n  }\n}","variables":{}}'
# pip install safegraphQL
import safegraphql.client as sgql

sgql_client = sgql.HTTP_Client(apikey = 'your-api-key')

brand = 'Starbucks'
city = 'Denver'
region = 'CO'
cols = [
    'location_name',
    'street_address',
    'polygon_wkt',
    'polygon_class',
    'includes_parking_lot',
    'is_synthetic'
]

sgql_client.search(product = 'geometry', brand = brand, city = city, region = region, columns = cols, max_results = 5)
import os
import requests
import json

headers = {
    'Content-Type': 'application/json',
    'apikey': '{your-api-key}'
}

query = """
query{
  search(first: 5 filter:{
    brand:"Starbucks"
    address: {
      city:"Denver"
      region: "CO"
    }
  }) {
    places {
      edges {
        node {
          placekey
          safegraph_geometry{
            location_name
            street_address
            polygon_wkt
            polygon_class
            includes_parking_lot
            is_synthetic
          }
        }
      }
    }
    
  }
}
"""

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

r_json = req.json()
print (json.dumps(r_json, indent=4, sort_keys=True))
{
  "data": {
    "search": {
      "places": {
        "edges": [
          {
            "node": {
              "placekey": "[email protected]",
              "safegraph_geometry": {
                "location_name": "Starbucks",
                "street_address": "7777 E Hampden Ave",
                "polygon_wkt": "POLYGON ((-104.8999285697937 39.654614050795956, -104.89980518817902 39.654403415686595, -104.90022361278534 39.65430016294756, -104.90033090114594 39.65450253817094, -104.8999285697937 39.654614050795956))",
                "polygon_class": "OWNED_POLYGON",
                "includes_parking_lot": null,
                "is_synthetic": false
              }
            }
          },
          {
            "node": {
              "placekey": "[email protected]",
              "safegraph_geometry": {
                "location_name": "Starbucks",
                "street_address": "9925 E Hampden Ave",
                "polygon_wkt": "POLYGON ((-104.87311438967487 39.6532728683004, -104.873114079457 39.65342099105103, -104.87297193088692 39.65342047478039, -104.87297223259708 39.65327261016452, -104.87311438967487 39.6532728683004))",
                "polygon_class": "OWNED_POLYGON",
                "includes_parking_lot": false,
                "is_synthetic": false
              }
            }
          },
          {
            "node": {
              "placekey": "[email protected]",
              "safegraph_geometry": {
                "location_name": "Starbucks",
                "street_address": "6395 E Hampden Ave",
                "polygon_wkt": "POLYGON ((-104.9159077747457 39.6536787217925, -104.91587089437175 39.653682851942165, -104.91586888271499 39.65370453522379, -104.91581054466891 39.65370453522379, -104.91581188577342 39.65368594955424, -104.91564894157577 39.6536849170169, -104.91564894157577 39.65358166320465, -104.91590911585021 39.653584760821275, -104.9159077747457 39.6536787217925))",
                "polygon_class": "OWNED_POLYGON",
                "includes_parking_lot": false,
                "is_synthetic": false
              }
            }
          },
          {
            "node": {
              "placekey": "[email protected]",
              "safegraph_geometry": {
                "location_name": "Starbucks",
                "street_address": "4505 Peoria St",
                "polygon_wkt": "POLYGON ((-104.84757173931939 39.778288818440984, -104.84771121418817 39.77828153047684, -104.84770450866563 39.778370443586574, -104.847681709889 39.778370443586574, -104.847681709889 39.77842437443324, -104.84766360497821 39.77842632330247, -104.84766427553046 39.778501449818364, -104.8475744215284 39.778497253888624, -104.84757173931939 39.778288818440984))",
                "polygon_class": "OWNED_POLYGON",
                "includes_parking_lot": null,
                "is_synthetic": false
              }
            }
          },
          {
            "node": {
              "placekey": "[email protected]",
              "safegraph_geometry": {
                "location_name": "Starbucks",
                "street_address": "4005 Chambers Rd",
                "polygon_wkt": "POLYGON ((-104.81088279280812 39.773426435665314, -104.81070576701313 39.77339963625025, -104.81071381364018 39.77333676065848, -104.81069369707257 39.77333160691892, -104.81070442590863 39.77328006950195, -104.81073258910328 39.77328728474266, -104.81074331793934 39.77324296253787, -104.81092034373432 39.773268731265055, -104.81088279280812 39.773426435665314))",
                "polygon_class": "OWNED_POLYGON",
                "includes_parking_lot": null,
                "is_synthetic": false
              }
            }
          }
        ]
      }
    }
  },
  "extensions": {
    "row_count": 5,
    "version_date": "1635494405__2021_10"
  }
}