Location Tutorial

In This Tutorial

This tutorial covers how to construct and execute an API request to the /locations endpoint, using a zip code as a filter.

Introduction to the Location API

The /locations endpoint allows for clients to determine if a location exists, search for a specific location by Id, and search for a list of locations by a given criteria (filter).

Construct and Execute a Location API Request

The location request is initiated when the user enters a zip code in the HTML form on the demo application. The code example below obtains the zip code and passes it to the getLocations() function as a parameter. The function then constructs the location request, passing the zip code as a filter.

The previously stored access token described in the Authorization Tutorial is used in the “Authorization” header.

location.js file (client side)

// Creates location request and display returned data on click
async function locationOnClick() {
  let zipCode = document.getElementById("locationSearchZipCode").value;
  const locations = await getLocations(zipCode);

async function getLocations(zipCode) {
  // Use stored access token for location request
  let accessToken = authentication.getAccessToken();
  // Build location URL
  // Base URL (
  // Version/Endpoint (/v1/locations)
  // Query String (?filter.zipCode.near=term)
  let locationUrl = `${
  // Location request body
  let locationResponse = await fetch(locationUrl, {
    method: "GET",
    cache: "no-cache",
    headers: {
      Authorization: `bearer ${accessToken}`,
      "Content-Type": "application/json; charset=utf-8"
  // Return JSON object
  return locationResponse.json();

Example Location Request and Response

A sample location request and JSON response are shown below.

Example Location request

curl -X GET \{{ZIPCODE}} \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'Cache-Control: no-cache' 
The example below has been shortened. The returned object may provide large amounts of data depending on the location size and number of locations returned.

Example Response JSON Object

    "data": [
            "locationId": "01400722",
            "chain": "KROGER",
            "address": {
                "addressLine1": "10101 Landing Way",
                "city": "Miamisburg",
                "state": "OH",
                "zipCode": "45342",
                "county": "MONTGOMERY COUNTY"
            "geolocation": {
                "latitude": 39.6023578,
                "longitude": -84.2302926,
                "latLng": "39.6023578,-84.2302926"
            "name": "Kroger - Austin Pike Landing",
            "hours": {
                "timezone": "America/New_York",
                "gmtOffset": "(UTC-05:00) Eastern Time (US Canada)",
                "open24": false,
                "monday": {
                    "open": "05:00",
                    "close": "01:00",
                    "open24": false
                "Tuesday": {..},
                "Wednesday": {..},
                "Thursday": {..},
                "Friday": {..},
                "Saturday": {..},
                "Sunday": {..},
            "phone": "9373844200",
            "departments": {
                "departments": {..},
                "departments": {..},

Set and Store a Selected Location

The code example below demonstrates one way to store the locationId after the end user selects a location from the returned list. The locationId can be used as a filter in other subsequent API requests.

location.js file (client side) Cont.

async function setLocationOnClick(event) {
  // store the locationId

// Clear the locationId when the user Signs Out of the application
async function clearLocation() {

Next Steps

Now that you have seen one possible way to implement the Location API, we recommend checking out the Product API Tutorial. The product tutorial covers how to construct and execute a product API request using a search term and the locationId discussed in this tutorial.

For more information on the /locations endpoints and a full list of acceptable filters, see our Swagger Documentation Page.