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": "[email protected]",
                  "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": "[email protected]",
                  "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": "[email protected]",
                  "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": "[email protected]",
                  "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": "[email protected]",
                  "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"
    ]
  }
}