--- updatedAt: 2026-07-17T21:11:16.000Z agentTools: projectIndex: https://hub.locally.com/llms.txt --- # Locate products at stores by style or UPC Given a style or a list of UPCs, locate stores that have the product in stock. ## 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 cURL 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' ``` ```javascript JavaScript 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(); ``` ```python Python 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 ```json JSON { "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](https://hub.locally.com/lcly/docs/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. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "External Headless API", "description": "Welcome to Locally's Headless API documentation. With our Headless API.", "version": "1.0" }, "servers": [ { "url": "https://www.locally.com" } ], "paths": { "/headless/api/1.0/product/locate": { "get": { "tags": [ "Product" ], "summary": "Locate products at stores by style or UPC", "description": "Given a style or a list of UPCs, locate stores that have the product in stock.", "operationId": "HeadlessAPIController::product_locate", "parameters": [ { "name": "Locally-Api-Token", "in": "header", "description": "Locally API token must be passed in the header to authenticate the API consumer", "required": true, "schema": { "type": "string" } }, { "name": "company_id", "in": "query", "description": "The ID of the company.", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "map_center_lat", "in": "query", "description": "The latitude of the geographical region center.", "required": true, "schema": { "type": "string" } }, { "name": "map_center_lng", "in": "query", "description": "The longitude of the geographical region center.", "required": true, "schema": { "type": "string" } }, { "name": "radius_in_miles", "in": "query", "description": "The radius of the geographical region in miles.", "required": false, "schema": { "type": "integer", "format": "int32", "example": 200 } }, { "name": "radius_in_km", "in": "query", "description": "The radius of the geographical region in kilometers.", "required": false, "schema": { "type": "integer", "format": "int32", "example": 100 } }, { "name": "only_show_country", "in": "query", "description": "Limit results to a specific country code e.g. US, CA, etc.", "required": false, "schema": { "type": "string", "example": "US" } }, { "name": "n_results", "in": "query", "description": "The number of stores to return. The default is 3.", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "upc", "in": "query", "description": "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.", "required": false, "schema": { "type": "string" } }, { "name": "style", "in": "query", "description": "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.", "required": false, "schema": { "type": "string" } }, { "name": "color", "in": "query", "description": "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.", "required": false, "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "The name of the dealer category.", "required": false, "schema": { "type": "string" } }, { "name": "paths_to_purchase", "in": "query", "description": "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.", "required": false, "schema": { "type": "string", "example": "ropis,bopis" } } ], "responses": { "200": { "description": "Successful" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "402": { "description": "Request Failed" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Server Error" } }, "security": [ { "HeaderAuthentication": [] } ] } } } } ```