Get location data

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.
`type` 🔗	string	Yes	The Type of requested location data store/dealer. One of: `store`, `dealer`.
`id` 🔗	integer	Yes	The ID of the store/dealer for which to retrieve information.
`upc`	string	Yes	The UPC of the product.
`company_id`	integer	Yes	The ID of the company.

Example Request

curl --get 'https://www.locally.com/headless/api/1.0/conversion/location_data/store/{{STORE_ID}}' \
--header 'Locally-Api-Token: {{API_TOKEN}}' \
--data-urlencode 'company_id={{COMPANY_ID}}' \
--data-urlencode 'upc={{UPC}}'

const response = await fetch(
  'https://www.locally.com/headless/api/1.0/conversion/location_data/store/{{STORE_ID}}?company_id={{COMPANY_ID}}&upc={{UPC}}',
  {
    headers: {
      'Locally-Api-Token': '{{API_TOKEN}}'
    }
  }
);
const data = await response.json();

import requests

response = requests.get(
    'https://www.locally.com/headless/api/1.0/conversion/location_data/store/{{STORE_ID}}',
    params={
        'company_id': '{{COMPANY_ID}}',
        'upc': '{{UPC}}'
    },
    headers={'Locally-Api-Token': '{{API_TOKEN}}'}
)
data = response.json()

The type path segment accepts store or dealer. The upc you pass scopes the product-specific parts of the response: acquisition_options and price_object reflect that product's availability and pricing at this location.

Example Response

{
  "success": true,
  "data": {
    "store_data": {
      "data": {
        "id": 37175,
        "company_id": 999,
        "name": "ACME Outfitters Chicago",
        "address": "15 ACME Ave",
        "city": "Chicago",
        "state": "IL",
        "zip": "60647",
        "country": "US",
        "lat": "41.91136867",
        "lng": "-87.67771437",
        "phone": "(312) 555-0142",
        "phone_link": "tel:+13125550142",
        "image": "image.jpg",
        "web_address": "https://www.acmeco.com",
        "dow": 0,
        "display_dow": [
          {
            "bil_hrs": "7am-8pm",
            "label": "Monday",
            "day_index": 0
          }
        ],
        "today_hours": "7am-8pm",
        "hour_status": "7am-8pm",
        "hours_known": 1,
        "is_open": 1,
        "is_closing_soon": 0,
        "is_tmp_closed": 0,
        "next_open": "",
        "status_class": "success",
        "status_label": "Open",
        "company": {
          "id": 999,
          "name": "ACME Outfitters",
          "address": "15 ACME Ave",
          "zip": "60647",
          "phone": "(312) 555-0175",
          "logo": "logo.jpg",
          "custom_cart_text": ""
        },
        "store_vat_details": {
          "id": 37175,
          "uses_vat": 0,
          "sales_tax_label": "Sales Tax"
        },
        "tmp_store_disclaimer": 0
      },
      "product_is_dropship": 0,
      "acquisition_options": {
        "bopis": 1,
        "ropis": 1
      },
      "user_distance": 1.2,
      "distance_info": {
        "distance": "1.2",
        "unit": "mi",
        "rate": 1,
        "string": "1.2 mi"
      }
    },
    "price_object": {
      "display": 1,
      "min": 225,
      "max": 225,
      "forced_currency": "USD",
      "range_currency": "USD",
      "usable_currency": "USD",
      "n_store_prices": 1,
      "n_msrp_prices": 1,
      "n_custom_prices": 0,
      "currency_symbol": "$",
      "string": "225",
      "variant_price_string": "225",
      "variant_price_value": 225,
      "origin": "MSRP",
      "origin_class": "msrp",
      "mutable": 1
    },
    "session": {
      "id": "abc999"
    }
  },
  "msg": ""
}

Response Explanation

success — Boolean outcome of the call. When false, the response also carries a top-level error_code and explanatory msg — always check success, not just the HTTP status.
data.store_data.data.id — The store (or dealer) named by the type/id path segments — the same ID as markers[].id in Get inventory data. company_id is the retailer company that owns it.
data.store_data.data.dow — Today's index (store-local time) into display_dow, whose bil_hrs are each day's opening hours. today_hours/hour_status are today's display line; while closed, hour_status shows the next-open string.
data.store_data.data.is_open — Live open flag in store-local time. status_class/status_label pair as success/Open or warning/Closed, next_open fills only while closed, and all empty out when hours_known is 0; is_tmp_closed flags temporary closures.
data.store_data.data.store_vat_details — Tax display hints from the store's country: uses_vat (1 in VAT countries) and the sales_tax_label to render (Sales Tax, VAT, ...).
data.store_data.product_is_dropship — 1 when the upc you passed reaches this store via brand ship-to-store rather than shelf stock: dropshippable product, no physical stock here, dropship-capable store.
data.store_data.acquisition_options — Paths to purchase for the requested UPC — bopis (buy online, pick up in store), ropis (reserve, pick up in store), sdd (same-day delivery), sts (ship to store); null when the store has neither a displayable price nor an affiliate link.
data.store_data.user_distance — Miles from the shopper's session location. distance_info localizes it — converted to km outside the US/GB (rate is the multiplier) with a display-ready string; note distance_info.distance is a string.
data.price_object.display — 1 when a price may be shown; otherwise purchase UI is suppressed. origin/origin_class say where it comes from: MSRP/msrp (list price only) or In-store/in-store (store-set prices only).
data.price_object.min — Range low in usable_currency (max equals it for one price). n_store_prices/n_msrp_prices/n_custom_prices count the sources; string is display-ready; mutable 1 means MSRP stays valid across variant switches.
data.session.id — Locally session ID, returned on every response. Replay it via the Locally-Api-Session-Id header to persist the shopper's session between calls; expired IDs are transparently replaced with fresh ones.
msg — Human-readable error text; empty string on success. In production, unexpected server errors are masked as App server error with a lookup reference — see Handling Errors in Production.