Locate products at stores by style or UPC

Request Parameters

🏷️ header · 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.
`company_id`	integer	Yes	The ID of the company.
`map_center_lat`	string	Yes	The latitude of the geographical region center.
`map_center_lng`	string	Yes	The longitude of the geographical region center.
`radius_in_miles`	integer	No	The radius of the geographical region in miles.
`radius_in_km`	integer	No	The radius of the geographical region in kilometers.
`only_show_country`	string	No	Limit results to a specific country code e.g. US, CA, etc.
`n_results`	integer	No	The number of stores to return. The default is 3.
`upc`	string	No	The UPC code(s) of the item. For multiple UPCs, please specify be a comma-separated list. Use instead of style or color. Required if style and color are not provided.
`style`	string	No	The brand's style identifier as stored in Locally (typically the `style_number` from the brand's product feed). Retrieves stores and in-stock data for related UPC codes. Resolves within the `company_id` scope — for cross-brand lookups, the company_id must belong to the product owner. Use UPC if the owner is unknown. Use instead of UPC or color. Required if UPC and color are not provided.
`color`	string	No	The ID of the color. Retrieves stores and in-stock data for related UPC codes. Use instead of UPC or style. Required if UPC and style are not provided.
`category`	string	No	The name of the dealer category.
`paths_to_purchase`	string	No	Comma delimited list of paths to purchase to filter by. Valid statuses are bopis, ropis, sdd and sts. If no paths to purchase supplied then all paths to purchase are returned.

Example Request

curl --get 'https://www.locally.com/headless/api/1.0/product/locate' \
--header 'Locally-Api-Token: {{API_TOKEN}}' \
--data-urlencode 'company_id={{COMPANY_ID}}' \
--data-urlencode 'style={{STYLE}}' \
--data-urlencode 'map_center_lat=41.8756719' \
--data-urlencode 'map_center_lng=-87.6243469' \
--data-urlencode 'radius_in_miles=200' \
--data-urlencode 'only_show_country=US' \
--data-urlencode 'n_results=3'

const params = new URLSearchParams({
  company_id: '{{COMPANY_ID}}',
  style: '{{STYLE}}',
  map_center_lat: '41.8756719',
  map_center_lng: '-87.6243469',
  radius_in_miles: '200',
  only_show_country: 'US',
  n_results: '3'
});

const response = await fetch(
  `https://www.locally.com/headless/api/1.0/product/locate?${params}`,
  {
    headers: { 'Locally-Api-Token': '{{API_TOKEN}}' }
  }
);
const data = await response.json();

import requests

response = requests.get(
    'https://www.locally.com/headless/api/1.0/product/locate',
    headers={'Locally-Api-Token': '{{API_TOKEN}}'},
    params={
        'company_id': '{{COMPANY_ID}}',
        'style': '{{STYLE}}',
        'map_center_lat': '41.8756719',
        'map_center_lng': '-87.6243469',
        'radius_in_miles': 200,
        'only_show_country': 'US',
        'n_results': 3,
    },
)
data = response.json()

Identify the product with exactly one of upc (accepts a comma-separated list), style, or color. style resolves within the company_id scope, so a lookup for a product owned by another brand must pass the owner's company_id — use upc when the owner is unknown.

Example Response

{
  "success": true,
  "data": {
    "product": {
      "id": 123456,
      "long_description": "Waterproof three-season trail jacket with pit zips and an adjustable storm hood.",
      "name": "Trailblazer Jacket",
      "image": "image.jpg",
      "n_reviews": 12,
      "average_rating": 4.5,
      "style_number": "999",
      "company_id": 999,
      "company": {
        "id": 999,
        "address": "15 ACME Ave",
        "logo": "image.jpg",
        "name": "ACME Outfitters",
        "phone": "(312) 555-0175"
      },
      "upcs": [
        {
          "id": 111111,
          "code": "000000000001",
          "color_code": "BLK",
          "color_name": "Black",
          "size_1": "M",
          "size_2": "",
          "image_url": "image.jpg"
        },
        {
          "id": 111112,
          "code": "000000000002",
          "color_code": "BLK",
          "color_name": "Black",
          "size_1": "L",
          "size_2": "",
          "image_url": "image.jpg"
        }
      ]
    },
    "all_upcs_carried": [
      "000000000001",
      "000000000002",
      "000000000003"
    ],
    "markers": [
      {
        "id": 37175,
        "name": "ACME Outfitters Chicago",
        "distance": "6.0 mi",
        "address": "15 ACME Ave",
        "city": "Chicago",
        "state": "IL",
        "zip": "60647",
        "country": "US",
        "phone": "(312) 555-0142",
        "url": "",
        "has_stock": 1,
        "feature_constants": [
          {
            "key": "IN_STORE_PICKUP_AVAILABLE",
            "value": "Store Pickup Available"
          }
        ],
        "status_label": "Open",
        "status_class": "success",
        "today_hours": "7am-8pm",
        "next_open": "",
        "hours_known": 1,
        "is_tmp_closed": 0
      }
    ],
    "session": {
      "id": "abc999"
    }
  },
  "msg": ""
}

Response Explanation

success — true with an empty msg on success. When no nearby store carries the product, the API instead returns success: false with error_code 1105 and a not-found msg.
data.product.upcs[] — Only variants whose code (the scannable UPC) appears in all_upcs_carried, with their color and size attributes. id here — like data.product.id — is a Locally-internal record ID.
data.all_upcs_carried[] — Every UPC variant of the product in stock at stores in the searched region, most-carried first; use it to drive variant pickers (see Create a Product Locator).
data.markers[] — Nearby stores, nearest and best-stocked first, capped at the requested store count (3 by default). id is the Locally store ID other endpoints accept (e.g. only_store_id on conversion/store_data).
data.markers[].distance — Pre-formatted display string in the shopper's unit: miles for US and GB stores, kilometers elsewhere. Empty when the distance is unknown or 300+ miles.
data.markers[].has_stock — 1 when the store has the product (or the exact variant) in stock, 0 when it merely carries the brand without live stock of this product.
data.markers[].url — The store's own website when Locally knows it (empty string otherwise) — not a locally.com link.
data.markers[].feature_constants[] — Paths to purchase the store offers: stable key values DELIVERY_AVAILABLE, IN_STORE_PICKUP_AVAILABLE, or SHIP_TO_STORE_AVAILABLE with a localized display value.
data.markers[].status_label — Store-hours status: Open/Closed with matching status_class success/warning; both empty when hours_known is 0. next_open fills only while closed, and is_tmp_closed 1 flags a temporary closure.
data.session.id — Locally session identifier, returned on every Headless API response. Echo it back in the Locally-Api-Session-Id header so the shopper's location and cart persist across calls.