Using a Search query, you can leverage filters to discover a broad range of relevant locations. You can search places with specific NAICS codes, brands, regions and more. 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.
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.
You may request attributes from SafeGraph Places, Geometry, or Patterns data sets.
Inputs
Required Input: 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.
query {
search(
filter: {
# ... filter fields
}
)
} {
# ... requested data fields
}
Filter Fields
| Parameter | Description |
|---|---|
| address | Search with Address data type |
| phone_number | Phone Number of the Place |
| naics_code | NAICS code |
| brand_id | Brand ID |
| brand | Name of the Brand |
| by_radius | Search by Radius around a set of coordinates |
| category | Search by category tags, like "sushi" or "sports bar" |
| msa_number | Search by Metropolitan Statistic Area (MSA), defined here |
Filter Combinations
You can use multiple filters in your search. Most filters can be combined, with the following exception:
- Category and address can be used standalone, or combined with each other. They can not currently be combined with any other filters
Optional Inputs & Pagination
You can optionally specify the number of records to be returned in each response, as well as which records should be returned.
You can also use after for pagination.
| 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" |
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(
filter: {
address: {
city: "San Francisco",
region: "CA"
}
}
) {
places {
results (first:5 after: "10") {
edges {
node {
safegraph_core {
location_name
placekey
latitude
longitude
street_address
city
region
postal_code
iso_country_code
brands {
brand_id
brand_name
}
}
safegraph_geometry {
polygon_wkt
polygon_class
includes_parking_lot
is_synthetic
enclosed
}
}
}
}
}
}
}
{
"data": {
"search": {
"places": {
"results": {
"edges": [
{
"node": {
"safegraph_core": {
"location_name": "Isa Restaurant",
"placekey": "22b-222@5vg-7mw-q9f",
"latitude": 37.800128,
"longitude": -122.43748,
"street_address": "3324 Steiner St",
"city": "San Francisco",
"region": "CA",
"postal_code": "94123",
"iso_country_code": "US",
"brands": []
},
"safegraph_geometry": {
"polygon_wkt": "POLYGON ((-122.43770522395994 37.8001337830919, -122.43734849016096 37.80018358796599, -122.43733306745912 37.80011205967886, -122.43769382457162 37.80006649347463, -122.43770522395994 37.8001337830919))",
"polygon_class": "OWNED_POLYGON",
"includes_parking_lot": false,
"is_synthetic": false,
"enclosed": false
}
}
},
{
"node": {
"safegraph_core": {
"location_name": "San Francisco Municipal Transportation Agency Market St & 3rd St",
"placekey": "zzy-229@5vg-7gv-5fz",
"latitude": 37.787405,
"longitude": -122.403741,
"street_address": "Market St & 3rd St",
"city": "San Francisco",
"region": "CA",
"postal_code": "94103",
"iso_country_code": "US",
"brands": []
},
"safegraph_geometry": {
"polygon_wkt": "POLYGON ((-122.4036902383409 37.787386, -122.40369301645424 37.78739992093523, -122.40370107885316 37.78741247919233, -122.40371363633389 37.78742244548158, -122.40372945968271 37.787428844233176, -122.403747 37.78743104909271, -122.40376454031728 37.787428844233176, -122.4037803636661 37.78742244548158, -122.40379292114683 37.78741247919233, -122.40380098354575 37.78739992093523, -122.40380376165909 37.787386, -122.40380098354575 37.78737207906477, -122.40379292114683 37.78735952080767, -122.4037803636661 37.787349554518414, -122.40376454031728 37.78734315576682, -122.403747 37.787340950907286, -122.40372945968271 37.78734315576682, -122.40371363633389 37.787349554518414, -122.40370107885316 37.78735952080767, -122.40369301645424 37.78737207906477, -122.4036902383409 37.787386))",
"polygon_class": "SHARED_POLYGON",
"includes_parking_lot": null,
"is_synthetic": true,
"enclosed": false
}
}
},
{
"node": {
"safegraph_core": {
"location_name": "ChargePoint Network Charging Station",
"placekey": "223-224@5vg-7gq-5vf",
"latitude": 37.775115,
"longitude": -122.417751,
"street_address": "1455 Market St",
"city": "San Francisco",
"region": "CA",
"postal_code": "94103",
"iso_country_code": "US",
"brands": []
},
"safegraph_geometry": {
"polygon_wkt": "POLYGON ((-122.41767324772421 37.775114, -122.4176760253783 37.77512792096462, -122.41768408644442 37.77514047924823, -122.41769664184926 37.77515044555853, -122.41771246258232 37.77515684432363, -122.41773 37.77515904918782, -122.4177475374177 37.77515684432363, -122.41776335815075 37.77515044555853, -122.41777591355559 37.77514047924823, -122.41778397462171 37.77512792096462, -122.4177867522758 37.775114, -122.41778397462171 37.77510007903538, -122.41777591355559 37.775087520751775, -122.41776335815075 37.775077554441474, -122.4177475374177 37.77507115567637, -122.41773 37.775068950812184, -122.41771246258232 37.77507115567637, -122.41769664184926 37.775077554441474, -122.41768408644442 37.775087520751775, -122.4176760253783 37.77510007903538, -122.41767324772421 37.775114))",
"polygon_class": "SHARED_POLYGON",
"includes_parking_lot": null,
"is_synthetic": true,
"enclosed": false
}
}
},
{
"node": {
"safegraph_core": {
"location_name": "Will Sushi",
"placekey": "229-226@5vg-832-qvf",
"latitude": 37.762627,
"longitude": -122.465969,
"street_address": "1380 9th Ave",
"city": "San Francisco",
"region": "CA",
"postal_code": "94122",
"iso_country_code": "US",
"brands": []
},
"safegraph_geometry": {
"polygon_wkt": "POLYGON ((-122.46584148999995 37.76264372400004, -122.46583749399997 37.762575137000056, -122.46608647499994 37.76256420500005, -122.46609126399994 37.76263275800005, -122.46584148999995 37.76264372400004))",
"polygon_class": null,
"includes_parking_lot": false,
"is_synthetic": false,
"enclosed": false
}
}
},
{
"node": {
"safegraph_core": {
"location_name": "San Francisco Municipal Transportation Agency 18th St & Noe St",
"placekey": "zzy-222@5vg-7gz-3qz",
"latitude": 37.760949,
"longitude": -122.432929,
"street_address": "18th St & Noe St",
"city": "San Francisco",
"region": "CA",
"postal_code": "94114",
"iso_country_code": "US",
"brands": []
},
"safegraph_geometry": {
"polygon_wkt": "POLYGON ((-122.43284825853942 37.76096, -122.43285103566417 37.76097392099851, -122.4328590951941 37.7609864793127, -122.43287164820629 37.760996445647265, -122.4328874659244 37.76100284442794, -122.432905 37.7610050492975, -122.43292253407562 37.76100284442794, -122.43293835179372 37.760996445647265, -122.4329509048059 37.7609864793127, -122.43295896433584 37.76097392099851, -122.43296174146059 37.76096, -122.43295896433584 37.760946079001485, -122.4329509048059 37.760933520687296, -122.43293835179372 37.76092355435273, -122.43292253407562 37.76091715557205, -122.432905 37.76091495070249, -122.4328874659244 37.76091715557205, -122.43287164820629 37.76092355435273, -122.4328590951941 37.760933520687296, -122.43285103566417 37.760946079001485, -122.43284825853942 37.76096))",
"polygon_class": "SHARED_POLYGON",
"includes_parking_lot": null,
"is_synthetic": true,
"enclosed": false
}
}
}
]
}
}
}
},
"extensions": {
"row_count": 10,
"version_date": [
"safegraph_core: 1645948803__2022_02",
"safegraph_geometry: 1645948803__2022_02",
"safegraph_weekly_patterns2: 2022_01_11",
"safegraph_monthly_patterns: 2022_01_11"
]
}
}