BigCommerce
Storefront
GraphQL Storefront
Locations
Locations Queries

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
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:

Example request: Get location metafields
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:

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
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.

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
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.

Did you find what you were looking for?