Request Pricing Data

API Request Using A Single Filter

This API request retrieves all pricing data from the Chilled Juice collection (hMvD6m-q) where the price is less than $20, sorted from oldest to newest

import requests

API_KEY = "YOUR_SHELFGRAM_API_KEY"
ENDPOINT = "https://api.shelfgram.com/api/2/query/pricing"
payload = {
    "api_key": API_KEY,
    "filters": [
        {
            "collections": {"match": "hMvD6m-q"},
            "price": {"match": {"max": 19.99}}
        }
    ],
    "sort": "earliest_seen"
}
response = requests.post(ENDPOINT, json=payload)

API Request Using Multiple Filters

This API request retrieves all prices that are either

  1. Seen in the last 30 days and below the average price; OR

  2. Seen in the current year and have the Costco “death star”

import requests

API_KEY = "YOUR_SHELFGRAM_API_KEY"
ENDPOINT = "https://api.shelfgram.com/api/2/query/pricing"
payload = {
    "api_key": API_KEY,
    "filters": [
        {
            "dates": {"match": "l30"},
            "price_type": {"match": "discount"}
        },
        {
            "dates": {"match": "ytd"},
            "has_asterisk": {"match": True}
        }
    ]
}
response = requests.post(ENDPOINT, json=payload)

Requesting New Pricing Data

To retrieve the most recently added pricing data on Shelfgram, utilize the price_id filter along with the earliest_added sort option. This approach prioritizes the sequence of data addition rather than the date associated with the source photo.

Below is a Python script that demonstrates how to fetch and process only newly added prices:

import requests

API_KEY = "YOUR_SHELFGRAM_API_KEY"
ENDPOINT = "https://api.shelfgram.com/api/2/query/pricing"

# Retrieve the last processed price ID from storage
LAST_PROCESSED_PRICE_ID = get_last_price_id()

payload = {
    "api_key": API_KEY,
    "filters": [
        {
            "price_id": {"match": {"min": LAST_PROCESSED_PRICE_ID}}
        }
    ],
    "sort": "earliest_added",
    "cursor": None,
    "limit": 1000
}

while True:
    try:
        response = requests.post(ENDPOINT, json=payload)
        response.raise_for_status()
        data = response.json()
    except requests.RequestException as e:
        print(f"Error retrieving pricing data: {e}")
        break

    prices = data['data']
    process_pricing_data(prices)
    LAST_PROCESSED_PRICE_ID = prices[-1]['price_id']
    print(f"Processed new pricing data up to price ID: {LAST_PROCESSED_PRICE_ID}")

    if next_page := data.get('next_page'):
        payload['cursor'] = next_page
    else:
        print("All new pricing data has been processed")
        break

# Save the ID of the last processed price to storage
save_last_price_id(LAST_PROCESSED_PRICE_ID)

Requesting Prices in (Private) Collections

The private_collections filter will retrieve prices in all collections that are linked to the specified private collection(s).

Example

Suppose there’s a private collection with the ID "privateCollection1" that’s linked to 4 collections, "collection1", "collection2", "collection3", and "collection4".

To retrieve prices from all 4 of these collections, either of the following filters could be used

Option 1: Filter by Private Collection

filters = [
    {
        "private_collections": {"match": "privateCollection1"},
    }
]

Option 2: Filter By Collection

filters = [
    {
        "collections": {"match": ["collection1", "collection2", "collection3", "collection4"]}
    }
]

The private_collections and collections filters can also be combined - for example, the below filter retrieves pricing data from "collection1", "collection2", and "collection3"

filters = [
    {
        "private_collections": {"match": "privateCollection1"},
        "collections": {"exclude": "collection4"}
    }
]