Request Parameters

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

Example Request

curl 'https://www.locally.com/api/v2/reports/json/{{REPORT_UUID}}/1/0' \
--header 'Locally-Api-Token: {{API_TOKEN}}'

const response = await fetch(
  'https://www.locally.com/api/v2/reports/json/{{REPORT_UUID}}/1/0',
  {
    headers: {
      'Locally-Api-Token': '{{API_TOKEN}}'
    }
  }
);
const page = await response.json();

import requests

url = "https://www.locally.com/api/v2/reports/json/{{REPORT_UUID}}/1/0"
headers = {"Locally-Api-Token": "{{API_TOKEN}}"}

page = requests.get(url, headers=headers).json()

split_id is the split_name value of a split returned by the Report Index endpoint, and page_number is zero-based — loop from 0 up to (but not including) the total_pages value in the response properties to download a full split.

Example Response

{
  "version": 2,
  "status": true,
  "properties": {
    "uuid": "b5ed7f10-f632-11ed-b67e-0242ac120002",
    "current_page": 0,
    "split_name": "1",
    "total_pages": 94,
    "total": 9371,
    "per_page": 100,
    "report_date": "2023-05-19"
  },
  "content": [
    {
      "upc": "195699284975",
      "qoh": "4",
      "updated": "2023-05-06 06:23:59",
      "msrp": "279",
      "retailer_price": "279",
      "currency": "USD",
      "cap": "0",
      "auth_status": "AUTHORIZED"
    },
    {
      "upc": "195589067206",
      "qoh": "2",
      "updated": "2023-05-06 06:18:22",
      "msrp": "34.95",
      "retailer_price": "29.95",
      "currency": "USD",
      "cap": "0",
      "auth_status": "AUTHORIZED"
    },
    {
      "upc": "840116501738",
      "qoh": "1",
      "updated": "2023-05-06 06:32:02",
      "msrp": "",
      "retailer_price": "70",
      "currency": "USD",
      "cap": "0",
      "auth_status": "UNKNOWN"
    }
  ]
}

Response Explanation

• version — Reports API format version; 2 identifies the current report system.
• properties.split_name — Echo of the requested split_id. For ShopSense reports each split is one store, and split_name is that store's Locally store ID.
• properties.total_pages — Page count for the split at 100 rows per page; fetch pages 0 through total_pages - 1 to download it in full — see Download a Full ShopSense Report.
• properties.total — Total rows in this split across all pages — for ShopSense inventory, the number of in-stock UPC records at the store. Each page holds per_page (100) rows.
• properties.report_date — Date the report was last generated — the same uuid always serves the newest run. Reports regenerate daily or weekly depending on report type.
• content[] — One row per record — for ShopSense inventory, one in-stock UPC at the store. Columns are configurable per report, so your report's fields may differ from this example.
• content[].qoh — Quantity on hand — units of this UPC currently in stock at the store.
• content[].updated — When this UPC's stock level last changed in Locally's inventory data — not the report run date (that is report_date).
• content[].cap — The store's compare-at ("was") price for the UPC, used for strike-through displays; defaults to the item's MSRP when the store has not provided one.
• content[].auth_status — Whether the store is an authorized dealer for the product's brand: AUTHORIZED, UNAUTHORIZED (brand shares a dealer list and the store is not on it), or UNKNOWN (no dealer data).