Using a Search query, you can leverage filters to discover a broad range of relevant locations. You may search places with specific NAICS codes, brands, regions and more. You may combine search filters to get more specific results. For example, retrieve details of a place with brand A and city B.

The search result will include requested information on up to 20 places in a single request. For searches that return more than that limit, you can iterate through multiple requests using arguments or variables.

The following search features are available with the SafeGraph Search query:

Search Inputs

Use the Search filter parameters to specify the attributes that should inform the response. Provide a Search filter with a single field or multiple fields combined. Note the resulting POI in the response will have to fulfill all of the search filter criteria. You may request attributes from Safegraph Core, Geometry, or Pattern data sets.

Request Parameters: Search

Parameter

Description

first

Identifies the number of records to be returned in each response. "Return the first 10 records"

after

Identifies where in the list the record count should start for those searches that span more than a single response. "Return first 20 after 30"

filter

Contains the attributes that can be used for the search

Filter

The search filter contains multiple attributes that will can be used to identify relevant POIs. You may search for places using address, phone number, NAICS code, brand name, brand id and more.

Parameter

Description

address

Address of the location with Address data type

phone_number

Phone Number of the Place

naics_code

NAICS code

brand_id

Brand ID

brand

Name of the Brand

Address Type

You may use the Address attributes like location name, street address, city, region, postal code, ISO country code, etc. as 'filter' values in the search query.

Parameter

Description

location_name

Name of the location

street_address

Street Address

city

City

region

Region

postal_code

Postal Code

iso_country_code

Country Code

Example

As an example, here's a search for POI in a single city. In most cities, this will require more than one query to get the entire list. But here, using arguments, the query is specifying the first 5 records after 10. Essentially looking for records 11 - 15 in the list. The list of responses will always maintain the same order so arguments can be used to move up and down without double counting.

query {
  search(first: 5 filter: { 
    address: {
      city:"San Francisco"
      region: "CA"
    } 
  }) {
    placekey
    safegraph_core {
      location_name
      street_address
      city
      region
      top_category
    }
  }
}
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 after: 10 filter: { \n    address: {\n      city:\"San Francisco\"\n      region: \"CA\"\n    } \n  }) {\n    placekey\n    safegraph_core {\n      location_name\n      street_address\n      city\n      region\n      top_category\n    }\n  }\n}","variables":{}}'
import requests
import json

url = "https://api.safegraph.com/v1/graphql"

payload="{\"query\":\"query {\\n  search(first: 5 after: 10 filter: { \\n    address: {\\n      city:\\\"San Francisco\\\"\\n      region: \\\"CA\\\"\\n    } \\n  }) {\\n    placekey\\n    safegraph_core {\\n      location_name\\n      street_address\\n      city\\n      region\\n      top_category\\n    }\\n  }\\n}\",\"variables\":{}}"
headers = {
  'apikey': '{your-api-key}',
  'content-type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)
{
  "data": {
    "search": [
      {
        "placekey": "zz[email protected]",
        "safegraph_core": {
          "location_name": "Sam's",
          "street_address": "618 Broadway",
          "city": "San Francisco",
          "region": "CA",
          "top_category": "Restaurants and Other Eating Places"
        }
      },
      {
        "placekey": "[email protected]",
        "safegraph_core": {
          "location_name": "Ruru Kitchen",
          "street_address": "532 Market St",
          "city": "San Francisco",
          "region": "CA",
          "top_category": "Restaurants and Other Eating Places"
        }
      },
      {
        "placekey": "[email protected]",
        "safegraph_core": {
          "location_name": "Stript Wax Bar",
          "street_address": "1764 Union St",
          "city": "San Francisco",
          "region": "CA",
          "top_category": "Personal Care Services"
        }
      },
      {
        "placekey": "[email protected]",
        "safegraph_core": {
          "location_name": "Eggxotic",
          "street_address": "3251 20th Ave",
          "city": "San Francisco",
          "region": "CA",
          "top_category": "Grocery Stores"
        }
      },
      {
        "placekey": "[email protected]",
        "safegraph_core": {
          "location_name": "Ma'velous",
          "street_address": "1408 Market St",
          "city": "San Francisco",
          "region": "CA",
          "top_category": "Drinking Places (Alcoholic Beverages)"
        }
      }
    ]
  },
  "extensions": {
    "row_count": 5,
    "version_date": "1627739802__2021_07"
  }
}