Search Photos

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

Requesting Photo Data

To retrieve photo 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/photos

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 photos. Must be one of the following values:

Value	Description
`recently_taken`	Sorts photos by date taken, from newest to oldest
`earliest_taken`	Sorts photos by date taken, from oldest to newest
`recently_added`	Sorts photos by the date added to Shelfgram, from newest to oldest
`earliest_added`	Sorts photos by the date added to Shelfgram, from oldest to newest

Type: str
Default: "recently_taken"

`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 address and categories fields in the response data, provide either

fields = ["address", "categories"]

or

fields = "address,categories"

in the body of your POST request.

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

{
    "data": [
        {
            "address": "1000 North Rengstorff Avenue",
            "categories": ["Analgesics & Pain Care"]
        },
        {
            "address": "8712 W LINEBAUGH AVE",
            "categories": ["Popcorn", "Private Label & Store Brands"]
        },
        ...
    ],
    ...
}

`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 photos.

About Filters

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

If multiple filters are provided, the conditions of at least one filter must be satisfied for a photo 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 photos that match the provided value(s)
`exclude`	Excludes photos that match the provided value(s)

…

Example Filter

The filter below contains two conditions.

It matches photos taken at Costco (c1N21iMY) or Walmart (I5gONaA) in all countries except for The United States (bkO6Cjp)

filters = [
    {
        "retailers": {"match": ["c1N21iMY", "I5gONaA"]},
        "countries": {"exclude": "bkO6Cjp"}
    }
]

Available Filters

The following filters are available for use in filter conditions

…

brands

The brands tagged in the photo.

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

categories

The categories tagged in the photo.

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

channels

The channels tagged in the photo.

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

collections

The collections tagged in the photo.

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

cities

The city the photo was taken in.

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

countries

The country the photo was taken in.

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

dates

The date the 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 photos from the current year.
`currentMonth`	Matches photos from the current month.
`lastMonth`	Matches photos from the previous month.
`today`	Matches photos from the current day.
`yesterday`	Matches photos from the previous day.
`l7`	Matches photos from the last 7 days.
`l30`	Matches photos from the last 30 days.
`l90`	Matches photos from the last 90 days.
`l365`	Matches photos from the last 365 days.
`p30`	Matches photos from the 30-day period starting 60 days ago.
`p90`	Matches photos from the 90-day period starting 180 days ago.
`p365`	Matches photos 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" and "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 photo was taken at.

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

locations

The location the photo was taken at.

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

months

The month the photo was taken.

Value: Integer between 1 and 12
Type: Union[int, List[int]]

postal_zip

The postal/zip code of the location the photo was taken at.

Type: str

products

The products tagged in the photo.

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

regions

The region the photo was taken in.

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

retailers

The retailer the photo was taken at.

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

states

The state the photo was taken in.

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

tags

The tags associated with the photo.

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

text

Text found within the photo

Type: str

Text can be searched in two ways

1. Exact Phrase Match
Text with double quotes will match photos containing the phrase exactly as is

2. Keyword Match
Text without double quotes will match photos containing all words in the phrase, regardless of the order they appear

…

Response Body Format

{
    "data": [
        {
            "address": str,
            "brands": List[str],
            "categories": List[str],
            "city": str,
            "collections": List[str],
            "country": str,
            "country_acronym": str,
            "date_taken": str,
            "demography": str,
            "image_url": str,
            "lat": float,
            "lng": float,
            "location": str,
            "location_postal_zip": str,
            "location_store_num": str,
            "photo_height": int,
            "photo_width": int,
            "products": [
                {
                    "name": str,
                    "price": float,
                    "sku": str,
                },
                ...
            ],
            "retailer": str,
            "state": str,
            "tags": List[str],
        },
        ...
    ],
    "count": int,
    "total_found": int,
    "next_page": Optional[int],
}

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 photos from the Acne Treatments category (uKuGhXS) that were taken in the last 30 days, sorted from oldest to newest

import requests

API_KEY = "YOUR_SHELFGRAM_API_KEY"
ENDPOINT = "https://api.shelfgram.com/api/2/query/photos"
payload = {
    "api_key": API_KEY,
    "filters": [
        {
            "categories": {"match": "uKuGhXS"},
            "dates": {"match": "l30"}
        }
    ],
    "sort": "earliest_taken"
}
response = requests.post(ENDPOINT, json=payload)

API Request Using Multiple Filters

This API request retrieves all photos that are either

Taken in Toronto (51DobYI); OR
Not taken in Toronto, but contain the text "Toronto"

import requests

API_KEY = "YOUR_SHELFGRAM_API_KEY"
ENDPOINT = "https://api.shelfgram.com/api/2/query/photos"
payload = {
    "api_key": API_KEY,
    "filters": [
        {
            "cities": {"match": "51DobYI"}
        },
        {
            "cities": {"exclude": "51DobYI"},
            "text": {"match": "Toronto"}
        }
    ]
}
response = requests.post(ENDPOINT, json=payload)