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.
query {
inventory {
locations {
edges {
node {
entityId
code
label
description
typeId
timeZone
address {
city
address1
address2
postalCode
stateOrProvince
email
phone
latitude
longitude
countryCode
}
operatingHours {
sunday {
open
opening
closing
}
monday {
open
opening
closing
}
tuesday {
open
opening
closing
}
wednesday {
open
opening
closing
}
thursday {
open
opening
closing
}
friday {
open
opening
closing
}
saturday {
open
opening
closing
}
}
specialHours {
label
open
opening
closing
}
}
}
}
}
}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:
query {
inventory {
locations {
edges {
node {
metafields(namespace: "examplespace") {
edges {
node {
entityId
key
value
}
}
}
entityId
code
label
description
typeId
}
}
}
}
}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:
...
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:
query {
inventory {
locations (
entityIds: [2]
codes: ["BC-LOCATION-2"]
typeIds: ["PHYSICAL"]
) {
edges {
node {
entityId
code
label
description
typeId
distance {
value
lengthUnit
}
timeZone
address {
city
address1
address2
postalCode
stateOrProvince
email
phone
latitude
longitude
countryCode
}
operatingHours {
sunday {
open
opening
closing
}
monday {
open
opening
closing
}
tuesday {
open
opening
closing
}
wednesday {
open
opening
closing
}
thursday {
open
opening
closing
}
friday {
open
opening
closing
}
saturday {
open
opening
closing
}
}
specialHours {
label
open
opening
closing
}
}
}
}
}
}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.
...
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:
query {
inventory {
locations (
countryCodes: [US]
states: ["TX"]
cities: ["Austin"]
distanceFilter: {
radius: 1.0
longitude: 122.4194
latitude: 37.7749
lengthUnit: Kilometres
}
) {
edges {
node {
entityId
code
label
description
typeId
distance {
value
lengthUnit
}
timeZone
address {
city
address1
address2
postalCode
stateOrProvince
email
phone
latitude
longitude
countryCode
}
operatingHours {
sunday {
open
opening
closing
}
monday {
open
opening
closing
}
tuesday {
open
opening
closing
}
wednesday {
open
opening
closing
}
thursday {
open
opening
closing
}
friday {
open
opening
closing
}
saturday {
open
opening
closing
}
}
specialHours {
label
open
opening
closing
}
}
}
}
}
}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.