StorefrontGuidesGraphQL StorefrontLocations

Query Locations with the GraphQL Storefront API

The GraphQL Storefront API allows you to fetch data for your store’s locations. Below are examples of GraphQL Storefront queries that allow you to fetch location data for storefront locations.

For a general overview of the GraphQL Storefront API usage and capabilities, see GraphQL Storefront API Overview. See GraphQL Playground for documentation of the full schema.

How to get location data for stores

You can retrieve location data for store locations that are enabled and visible. Here is an example query that returns location data, for example, address and operating hours on the specified days.

Example request: Get location data
1query {
2  inventory {
3    locations {
4      edges {
5        node {
6          entityId
7          code
8          label
9          description
10          typeId
11          timeZone
12          address {
13            city
14            address1
15            address2
16            postalCode
17            stateOrProvince
18            email
19            phone
20            latitude
21            longitude
22            countryCode
23          }
24          operatingHours {
25            sunday {
26              open
27              opening
28              closing
29            }
30            monday {
31              open
32              opening
33              closing
34            }
35            tuesday {
36              open
37              opening
38              closing
39            }
40            wednesday {
41              open
42              opening
43              closing
44            }
45            thursday {
46              open
47              opening
48              closing
49            }
50            friday {
51              open
52              opening
53              closing
54            }
55            saturday {
56              open
57              opening
58              closing
59            }
60          }
61          specialHours {
62            label
63            open
64            opening
65            closing
66          }
67        }
68      }
69    }
70  }
71}

Locations are identified by a unique ID (entityId) and code (code). The location’s type ID (typeId) is the location type, either PHYSICAL or VIRTUAL. The location’s code and type can be customized using Locations API.

The location identities and data that are returned from the response can be used to filter the data returned for certain locations. See How to Filter Location Data.

When you query for metafields, only metafields with storefront access permissions will be returned. In other words, a metafield’s permission_set field must be write_and_sf_access or read_and_sf_access when you create or update a metafield. The following example includes the metafields along with the location data that are returned. As shown, the namespace of the metafield you wish to query must be specified:

Example request: Get location metafields
1query {
2  inventory {
3    locations {
4      edges {
5        node {
6          metafields(namespace: "examplespace") {
7            edges {
8              node {
9                entityId
10                key
11                value
12              }
13            }
14          }
15          entityId
16          code
17          label
18          description
19          typeId
20        }
21      }
22    }
23  }
24}

A location’s descriptions can be added using the Create locations endpoint in the Locations API. A location’s metafields can be added using Create a metafield endpoint in the Locations API.

How to filter location data

You can filter by the identities of locations, as well as the data for locations, so that data for only some locations will be returned. To do so, specify a filter in the argument for locations.

Filter by location identity

You can filter by the entityIds, codes, and typeIds of the locations you wish to return:

Filters for Location Identity
...
locations(
      entityIds: [1, 2, 3]
      codes: ["BC-LOCATION-2", "BC-LOCATION-1", "BC-LOCATION-3"]
      typeIds: ["PHYSICAL", "VIRTUAL"]
      )
...

Here is an example query that returns the locations that have a specific entityId, code, and typeId:

Example request: Get location data using ID filters
1query {
2  inventory {
3    locations (
4      entityIds: [2]
5      codes: ["BC-LOCATION-2"]
6      typeIds: ["PHYSICAL"]
7    ) {
8      edges {
9        node {
10          entityId
11          code
12          label
13          description
14          typeId
15          distance {
16            value
17            lengthUnit
18          }
19          timeZone
20          address {
21            city
22            address1
23            address2
24            postalCode
25            stateOrProvince
26            email
27            phone
28            latitude
29            longitude
30            countryCode
31          }
32          operatingHours {
33            sunday {
34              open
35              opening
36              closing
37            }
38            monday {
39              open
40              opening
41              closing
42            }
43            tuesday {
44              open
45              opening
46              closing
47            }
48            wednesday {
49              open
50              opening
51              closing
52            }
53            thursday {
54              open
55              opening
56              closing
57            }
58            friday {
59              open
60              opening
61              closing
62            }
63            saturday {
64              open
65              opening
66              closing
67            }
68          }
69          specialHours {
70            label
71            open
72            opening
73            closing
74          }
75        }
76      }
77    }
78  }
79}

Filter by location data

You can also filter for locations by their data. For example, you can filter by location country, state, and city. You can also filter for locations that are within a specified distance from a shopper, specified by latitude and longitude coordinates.

Filters for Location Data
...
locations(
      countryCodes: [US, AU]
      states: ["TX", "CA"]
      cities: ["Austin", "San Francisco"]
      distanceFilter: {
        radius: 1.0
        longitude: 122.4194
        latitude: 37.7749
        lengthUnit: Kilometres
      }
  )
...

When filtering by country, use the country’s two-letter code. For states, use the state abbreviation. When filtering by distance, specify distance in terms of Kilometres or Miles.

This example query returns the stores that are in the specified country, state, and city, and that are within one kilometer from the specified latitude and longitude:

Example request: Get location data using distance filters
1query {
2  inventory {
3    locations (
4      countryCodes: [US]
5      states: ["TX"]
6      cities: ["Austin"]
7      distanceFilter: {
8        radius: 1.0
9        longitude: 122.4194
10        latitude: 37.7749
11        lengthUnit: Kilometres
12      }
13    ) {
14      edges {
15        node {
16          entityId
17          code
18          label
19          description
20          typeId
21          distance {
22            value
23            lengthUnit
24          }
25          timeZone
26          address {
27            city
28            address1
29            address2
30            postalCode
31            stateOrProvince
32            email
33            phone
34            latitude
35            longitude
36            countryCode
37          }
38          operatingHours {
39            sunday {
40              open
41              opening
42              closing
43            }
44            monday {
45              open
46              opening
47              closing
48            }
49            tuesday {
50              open
51              opening
52              closing
53            }
54            wednesday {
55              open
56              opening
57              closing
58            }
59            thursday {
60              open
61              opening
62              closing
63            }
64            friday {
65              open
66              opening
67              closing
68            }
69            saturday {
70              open
71              opening
72              closing
73            }
74          }
75          specialHours {
76            label
77            open
78            opening
79            closing
80          }
81        }
82      }
83    }
84  }
85}

The distance from the queried latitude and longitude is returned in the response. In this example, one store location was returned, in which the store was located 0 km from the queried latitude and longitude.