Switch session location

Request Parameters

🏷️ header · 🔗 path · unmarked parameters are query params

Parameter	Type	Required	Description
`Locally-Api-Token` 🏷️	string	Yes	Locally API token must be passed in the header to authenticate the API consumer.
`Locally-Api-Session-Id` 🏷️	string	Yes	Session ID must be passed in the header to persist the user session. Can expire.
`lat` 🔗	number	Yes	The latitude coordinate of the new location. Must be a decimal number between -90 and 90.
`lng` 🔗	number	Yes	The longitude coordinate of the new location. Must be a decimal number between -180 and 180.
`location_change_to_string`	string	Yes	A required parameter to specify the location label. This parameter must be URL-encoded.

Example Request

curl --get 'https://www.locally.com/headless/api/1.0/location/switch/41.8756719/-87.6243469' \
--header 'Locally-Api-Token: {{API_TOKEN}}' \
--header 'Locally-Api-Session-Id: {{SESSION_ID}}' \
--data-urlencode 'location_change_to_string=Chicago, Illinois, United States.'

const response = await fetch(
  'https://www.locally.com/headless/api/1.0/location/switch/41.8756719/-87.6243469?location_change_to_string=Chicago,+Illinois,+United+States.',
  {
    headers: {
      'Locally-Api-Token': '{{API_TOKEN}}',
      'Locally-Api-Session-Id': '{{SESSION_ID}}'
    }
  }
);
const data = await response.json();

import requests

response = requests.get(
    "https://www.locally.com/headless/api/1.0/location/switch/41.8756719/-87.6243469",
    headers={
        "Locally-Api-Token": "{{API_TOKEN}}",
        "Locally-Api-Session-Id": "{{SESSION_ID}}",
    },
    params={"location_change_to_string": "Chicago, Illinois, United States."},
)
data = response.json()

The lat/lng path values and the URL-encoded location_change_to_string label typically come from the location suggest endpoint, and the Locally-Api-Session-Id header should carry the session ID returned by an earlier request so the location change persists for that shopper's session.

Example Response

{
  "success": true,
  "data": {
    "city_label": "Chicago, IL",
    "country": "US",
    "zip_label": "60604",
    "postal_code": "60604",
    "lat": "41.87758900",
    "lng": "-87.62818000",
    "source": "region",
    "base_url": "/in/chicago-il",
    "distance_unit": "mi",
    "session": {
      "id": "abc999"
    }
  }
}

Response Explanation

data.city_label — City, ST label for the region now stored on the session; subsequent calls sending the same Locally-Api-Session-Id automatically use this location.
data.lat / data.lng — Center coordinates of the nearest region Locally matched, returned as strings — expect them to differ slightly from the coordinates you requested.
data.zip_label / data.postal_code — Both carry the matched region's postal code; zip_label is the display variant, postal_code the raw value.
data.source — How the session location was resolved: region means it was matched against Locally's geographic region database; ip indicates IP-based geolocation instead.
data.base_url — Path of the locally.com multi-store search page for this location, e.g. /in/chicago-il; / when no city is resolved.
data.distance_unit — Unit used for distances at this location: mi for the US and GB, km everywhere else.
data.session.id — Session ID returned on every response. Pass it as the Locally-Api-Session-Id header on later calls to persist location and cart state; expired or missing IDs are replaced with fresh ones.