Download a Full ShopSense Report

Our Data Sharing API delivers ShopSense reports broken out by store ("Splits"). Each split can contain multiple pages of data. This guide walks you through how to programmatically download the full set of data using a script.

How It Works

• Your report has a main Index endpoint that returns a list of Splits—each representing a store.
• Each Split has an ID corresponding to the Locally ID of the store, and includes a first_page URL and a total_pages count.
• You’ll loop through each Split and download each page of its data.

📘

Store Identification

The "contents" of each split contains identifying store details, such as store name, address details and your vendor_id.

Step-by-Step Instructions

1. Make a request to the Index endpoint
This will return all the stores (Splits) in the report.

GET https://www.locally.com/api/v2/reports/json/[report_uuid]
Headers: 
  Locally-Api-Token: YOUR_API_KEY

2. Loop through each Split in the response

For each Split:

• Extract the split_name (store ID)
• Note the first_page URL
• Use total_pages to determine how many pages to request

3. Download each page of each Split

The page URLs follow the pattern:

{first_page_url_without_trailing_number}/{page_number}

4. Process each product record

Each page contains one or more inventory records (products) for that store.

Sample Pseudocode (Python)

⚠️ This is sample pseudocode meant to demonstrate the concept. You’ll need to adapt this to your production environment.

import requests

report_uuid = "YOUR_REPORT_UUID"
API_KEY = "YOUR_REPORT_API_KEY"

# Replace with actual UUID and your API key
INDEX_URL = f"https://www.locally.com/api/v2/reports/json/{report_uuid}"
HEADERS = {"Locally-Api-Token": API_KEY}

# Step 1: Fetch the index of all splits (stores)
index_response = requests.get(INDEX_URL, headers=HEADERS)
index_data = index_response.json()

# Step 2: Loop through each split/store
for split in index_data.get("content", []):
    split_id = split["split_name"]
    total_pages = split["total_pages"]
    base_url = split["first_page"].rsplit("/", 1)[0]  # Remove trailing '/0'

    # Step 3: Fetch each page for that split
    for page_num in range(total_pages):
        page_url = f"{base_url}/{page_num}"
        page_response = requests.get(page_url, headers=HEADERS)
        page_data = page_response.json()

        # Step 4: Process each product record
        for product in page_data.get("content", []):
            print(
                f"{product['store_name']} ({split_id}): "
                f"{product['product_name']} (UPC: {product['upc']}) - "
                f"Qty: {product['quantity_on_hand']} - "
                f"Price: {product['retailer_price']} - "
                f"Last updated: {product['updated']}"
            )

Example Output

Locally Test Store #1 (458758): Keith Richards Signature Telecaster (UPC: 848426073865) - Qty: 2 - Price: 5545  - Last updated: 2025-02-15

In this example, the data would be printed to standard output (the console or terminal where the script is run). For real-world usage, you'll want to update the script to store the data as you see fit (in your database, send to an API or internal tool, write to a CSV file, etc.).

📎 Additional Notes

• All requests must include a valid Locally-Api-Token in the header.
• Splits may include multiple pages (check total_pages)