Search Pricing Data

The query/pricing endpoint allows you to search Shelfgram’s pricing data using a variety of filters.

Requesting Pricing Data

To retrieve pricing data, make a POST request to the following endpoint with the Required Request Body Fields and any of the Optional Request Body Fields:

https://api.shelfgram.com/api/2/query/pricing

Warning

Please note that this API route allows a maximum of 5 requests per second

Required Request Body Fields

`api_key`

api_key

A valid Shelfgram Public API key

Note

Please see Getting Started if you don’t already have an API key

Type: str

Optional Request Body Fields

`sort`

sort

The method to use when sorting prices. Must be one of the following values:

Value	Description
`recently_seen`	Sorts prices by date seen, from newest to oldest
`earliest_seen`	Sorts prices by date seen, from oldest to newest
`recently_added`	Sorts prices by the date added to Shelfgram, from newest to oldest
`earliest_added`	Sorts prices by the date added to Shelfgram, from oldest to newest

Type: str
Default: "recently_seen"

`limit`

limit

The maximum number of items to return in each set of paginated results.

Type: int
Default: 500
Maximum: 1000

`fields`

fields

An array or comma-separated list of API response fields to return in the response data.

If not provided, all available fields will be returned.

Type: Union[str, List[str]]

Example: Filtering Response Data

To only include the price and sku_name fields in the response data, provide either

fields = ["price", "sku_name"]

or

fields = "price,sku_name"

in the body of your POST request.

The response will only contain a subset of the full pricing data:

{
    "data": [
        {
            "price": 19.99,
            "sku_name": "1597934"
        },
        {
            "price": 29.99,
            "sku_name": "4123588"
        },
        ...
    ],
    ...
}

Note

For internal users, the response data will always contain the photo_source_id and photo_source_url

`cursor`

cursor

The cursor to use when requesting the next page of results.

Obtained from the next_page field of an API response

Important

When retrieving the next page of results, you must use the same filters and sort values as the original request

Type: int

`filters`

filters

Type: List[Dict]

A list of filters to apply when searching for prices.

About Filters

A filter is a set of conditions that must be satisfied for a price to be a match.

If multiple filters are provided, the conditions of at least one filter must be satisfied for a price to be considered a match.

Filter Format

Each condition contains a key, operator, and an individual/list of values to filter on.

They must be formatted as either

{"filter_key": {"condition_operator": "filter_value"}}

or

{"filter_key": {"condition_operator": ["filter_value_1", "filter_value_2", ...]}}

where

"filter_key" is one of the available filters
"filter_value" is a landing page ID or filter-specific value
"condition_operator" is one of the following operators:

Condition Operators

Value	Description
`match`	Includes prices that match the provided value(s)
`exclude`	Excludes prices that match the provided value(s)

…

Example Filter

The filter below contains three conditions.

It matches pricing data where the brand is either Folgers or Keurig and the price is between $20.00 and $49.99, in all countries except for The United States (bkO6Cjp)

filters = [
    {
        "brands": {"match": ["Folgers", "Keurig"]},
        "price": {"match": {"min": 20, "max": 49.99}}
        "countries": {"exclude": "bkO6Cjp"}
    }
]

Available Filters

The following filters are available for use in filter conditions

…

brands

The brand of the SKU in the price tag.

Value: Brand Name (capitalized correctly)
Type: Union[str, List[str]]
Directory: Brands Directory

collections

The collections tagged in the source photo.

Value: Collection Landing Page ID
Type: Union[str, List[str]]

cities

The city the source photo was taken in.

Value: City Landing Page ID
Type: Union[str, List[str]]

countries

The country the source photo was taken in.

Value: Country Landing Page ID
Type: Union[str, List[str]]
Directory: Countries Directory

dates

The date the source photo was taken.

Value: Date Filter or Date Range
Type: Union[str, Dict[str, str]]

Important

The "exclude" operator cannot be used with the "dates" filter.

When filtering by dates, the filter value must be either

…

1. A Date Filter

Value	Description
`ytd`	Matches prices from the current year.
`currentMonth`	Matches prices from the current month.
`lastMonth`	Matches prices from the previous month.
`today`	Matches prices from the current day.
`yesterday`	Matches prices from the previous day.
`l7`	Matches prices from the last 7 days.
`l30`	Matches prices from the last 30 days.
`l90`	Matches prices from the last 90 days.
`l365`	Matches prices from the last 365 days.
`p30`	Matches prices from the 30-day period starting 60 days ago.
`p90`	Matches prices from the 90-day period starting 180 days ago.
`p365`	Matches prices from the 365-day period starting 730 days ago.

Example:

{"dates": {"match": "ytd"}}

…

2. A Custom Date Range

The date range must contain a "start_date" or "end_date" key

Example:

{"dates": {"match": {"start_date": "2024-01-01", "end_date": "2024-01-31"}}}

Note

The start and end dates are inclusive when using a custom date range

…

demographics

The demography of the location the source photo was taken at.

Value: Demography Landing Page ID
Type: Union[str, List[str]]

first_detected

The date of the first photo in Shelfgram’s database that contains the SKU

Tip

This format of this filter is the same as the dates filter

Value: Date Filter or Date Range
Type: Union[str, Dict[str, str]]

has_asterisk

Flag indicating if the Costco “death star” is present on the price tag

Type: bool

is_display

Flag indicating if the price tag is from a display

Type: bool

locations

The location the source photo was taken at.

Value: Location Landing Page ID
Type: Union[str, List[str]]

planogram_size

The size of the planogram containing the source photo

Type: int

planogram_position

The position of the source photo in its containing planogram.

Value: Any/all of "first", "middle", "last"
Type: Union[str, List[str]]

price

The price in the price tag.

Value: Price or Price Range
Type: Union[float, int, List[Union[float, int]], Dict[str, Union[float, int]]]

The filter value must be provided as either

…

1. A Single Price

{"price": {"match": 19.99}}

…

2. A Custom Price Range

The price range must contain a "min" and/or "max" key

Example:

{"price": {"match": {"min": 20, "max": 49.99}}}

Note

The min and max values are inclusive

…

price_avg

The average price of the product over the past 6 months.

Tip

This format of this filter is the same as the price filter

Value: Price or Price Range
Type: Union[float, int, List[Union[float, int]], Dict[str, Union[float, int]]]

price_id

The ID of the price, which corresponds to when the price was added to Shelfgram.

Hint

See Requesting New Pricing Data for an example of how to use this filter

Type: Union[int, List[int], Dict[str, int]]

price_type

A descriptor indicating how the price compares to the average price.

Price Types

Value	Description
`discount`	Matches prices that are lower than the average price.
`premium`	Matches prices that are higher than the average price.
`normal`	Matches prices that are the same as the average price.

Value: Price Type
Type: Union[str, List[str]]

private_collections

The private collections containing the source photo.

Value: Private Collection Landing Page ID
Type: Union[str, List[str]]

products

The product the price tag is for.

Value: Product Landing Page ID
Type: Union[str, List[str]]

retailers

The retailer the source photo was taken at.

Value: Landing Page ID
Type: Union[str, List[str]]
Directory: Retailers Directory

skus

The SKU code the price tag is for (ex. 1169847)

Hint

These can be found in the product name on product landing pages

Type: Union[str, int, List[Union[str, int]]]

states

The state the source photo was taken in.

Value: State Landing Page ID
Type: Union[str, List[str]]

year_month

The year/month combination that the source photo was taken.

Must be provided in the format "YYYY-MM"

Type: Union[str, List[str]]

…

Response Body Format

{
    "data": [
        {
            "city": str,
            "collection_ids": List[str],
            "collections": List[str],
            "country": str,
            "date_seen": str,
            "demography": str,
            "first_detected": str,
            "has_asterisk": bool,
            "is_display": bool,
            "location_address": str,
            "location_lat": float,
            "location_long": float,
            "location_store_num": str,
            "photo_image_url": str,
            "photo_source_id": str,
            "photo_source_url": str,
            "planogram_position": Optional[int],
            "planogram_position_type": Optional[str],
            "planogram_size": Optional[int],
            "price": float,
            "price_avg": float,
            "price_id": int,
            "price_image_url": str,
            "price_type": str,
            "product_image_url": str,
            "retailer": str,
            "sku_brand": str,
            "sku_name": str,
            "sku_summary": str,
            "state": str
        },
        ...
    ],
    "count": int,
    "total_found": int,
    "next_page": Optional[int],
}

Note

The photo_source_url and photo_source_id fields are only available for internal users

Required Response Fields

`data`

data

A list containing the data of matching items.

Type: List[Dict[str, Any]]

`count`

count

The number of items returned in the data array.

Type: int

`total_found`

total_found

The total number of items matching the filter criteria.

Type: int

Optional Response Fields

`next_page`

next_page

The cursor value to use when requesting the next page of results.

Tip

If this value is not present, all matching items have been retrieved.

Type: int

…

Example API Requests

The below sample requests use Python and requests

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

Seen in the last 30 days and below the average price; OR
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"}
    }
]