Get Holiday Benchmark Data
Benchmark the store against seasonal shopping events such as BFCM or Labor Day: the Holiday Index and the Brand Benchmark, as a snapshot or a time series.
Retrieve a seasonal event benchmarking snapshot (Holiday Index and Brand Benchmark) for a shopping event such as BFCM or Labor Day.
Returns a single KPI object summarizing the brand's performance across the requested window. To match the Intelligems dashboard's "Q4 to Date" tile, pass Oct 1 → Dec 31 of the event year. For time-indexed chart data across the event window, use POST /analytics/event/timeseries.
Enumerations
event — the seasonal event identifier:
"BFCM"— Black Friday / Cyber Monday"laborDay""memorialDay""presidentsDay"
metric — the KPI to return:
"revenue"— net revenue"orders"— order count"priceLevels"— average unit price
Request
event
yes
event enum
See above.
metric
yes
metric enum
See above.
year
no
integer (2021–2026)
Which event year. Defaults to the most recently completed occurrence.
start
yes
ISO 8601 datetime string
Beginning of the analysis window. For the dashboard Q4 view, pass Oct 1 of the event year.
end
yes
ISO 8601 datetime string
End of the analysis window. For the dashboard Q4 view, pass Dec 31 of the event year.
Response
periodToDateValue— brand actual value for the selected metric across the event window. Maps to the dashboard's "Q4 {Metric} to Date" tile.vsLastYear— percent change vs. the same period in the prior event year (e.g.0.12= +12%). Maps to the ±% pill on the "Q4 to Date" tile.avgDailyIndexPercent— the brand's average daily value as a percent of its own full-day baseline, across the window. Maps to the dashboard's "Avg Daily {Metric} (% of typical day)" tile.currentIndexPercent— the industry-wide average daily index across the window (percent of full-day baseline, aggregated across the ~1,000-brand basket). Maps to the dashboard's "Index (% of typical day)" tile.
All numeric fields are number | null.
Rate limits
Uses the same rate limit as the /analytics/sitewide/* endpoints. Aggregated, cacheable data — see the Rate Limiting Reference.
Rate Limit: 10 requests per 30s window, refilling 5 tokens every 30s.
Intelligems external API access token.
Seasonal event identifier. Supported values: "BFCM" (Black Friday / Cyber Monday), "laborDay", "memorialDay", "presidentsDay".
Metric to return. Supported values: "revenue" (net revenue), "orders" (order count), "priceLevels" (average unit price).
Which year of the event to fetch (e.g. 2025 for BFCM 2025). Defaults to the most recently completed occurrence of the event. The prior-year comparison cohort is always year - 1. For hourly granularity, leave this unset or pass a year matching end's year — passing a mismatched year + end will yield nonsensical results.
Required. Start of analysis period as an ISO 8601 datetime string. Used to size the window before the event (days-before-holiday); does not influence which event year is fetched. For hourly granularity, ignored. To match the Intelligems dashboard's Q4 view, pass Oct 1 of the event year (58 days before BFCM).
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$Required. End of analysis period as an ISO 8601 datetime string. Used to size the window after the event (days-after-holiday); does not influence which event year is fetched. For hourly granularity this is interpreted as "the day to analyze" and is expected to fall within year. To match the Intelligems dashboard's Q4 view, pass Dec 31 of the event year (33 days after BFCM).
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$OK
Too Many Requests
curl --location 'https://api.intelligems.io/v25-10-beta/analytics/event/snapshot' \
--header 'content-type: application/json' \
--header 'intelligems-access-token: YOUR_API_KEY' \
--data '{
"event": "BFCM",
"metric": "revenue",
"start": "2025-10-01T00:00:00.000-05:00",
"end": "2025-12-31T00:00:00.000-05:00"
}'{
"currency": "USD",
"snapshot": {
"periodToDateValue": 128450.75,
"vsLastYear": 0.184,
"avgDailyIndexPercent": 1.42,
"currentIndexPercent": 1.31
}
}Retrieve seasonal event benchmarking timeseries data (Holiday Index and Brand Benchmark) for a shopping event such as BFCM or Labor Day.
Returns a list of datapoints along the chosen x-axis, with value fields populated according to the chosen mode. Use this endpoint for time-indexed chart data across the event window. For a single period-to-date KPI summary, use POST /analytics/event/snapshot.
Enumerations
event — the seasonal event identifier:
"BFCM"— Black Friday / Cyber Monday"laborDay""memorialDay""presidentsDay"
metric — the KPI to return:
"revenue"— net revenue"orders"— order count"priceLevels"— average unit price
Request
event
yes
event enum
See above.
metric
yes
metric enum
See above.
xAxis
yes
"actualDate" | "daysFromEvent"
Controls how dt is labeled in the response.
granularity
yes
"hourly" | "daily"
hourly returns one datapoint per hour for the event day; daily returns one per day across the window.
mode
yes
"index" | "brand" | "brandWithIndex"
Controls which fields are populated per datapoint.
year
no
integer (2021–2026)
Which event year. Defaults to the most recently completed occurrence.
start
yes
ISO 8601 datetime string
Beginning of the analysis window. For the Q4 dashboard view, pass Oct 1 of the event year. Ignored for hourly.
end
yes
ISO 8601 datetime string
End of the analysis window. For the Q4 dashboard view, pass Dec 31 of the event year. For hourly, this is the single day to analyze.
With xAxis: "actualDate", each datapoint's dt is a full ISO datetime. With xAxis: "daysFromEvent", dt is a signed day offset as a string (e.g. "-3", "0", "2"). For granularity: "hourly", dt falls back to the ISO hour label regardless of xAxis.
Note on the
dailywindow. Forgranularity: "daily"the returned range is always widened to reach the event day, so the effective window is[min(start, eventDay), max(end, eventDay)]. Requestingstartandendthat both sit on one side of the event still returns every day between your range and the event: for BFCM 2025 (event day 2025-11-28),start2025-12-20T00:00:00Z/end2025-12-25T00:00:00Zreturns 28 datapoints beginning 2025-11-28, andstart2025-10-01T00:00:00Z/end2025-10-10T00:00:00Zreturns 59 datapoints ending 2025-11-28. Filter ondayOffsetordtclient-side if you need a sub-window that excludes the event day.Note also that the last bucket is rounded up to the next day boundary, so an
endof2025-12-05T23:59:59Zyields a finaldtof2025-12-06T00:00:00. That rounding adds a datapoint, so it compounds with the widening above — the first example sent withend2025-12-25T23:59:59Zinstead of2025-12-25T00:00:00Zreturns 29 datapoints, throughdt2025-12-26T00:00:00(dayOffset0 through 28). Both counts are correct; pass a day-alignedendwhen the datapoint count matters.
Note on prior-year windowing. Prior-year values on each datapoint align by days-from-event, not by calendar date. Because the event falls on a different calendar date each year (e.g. Black Friday is the fourth Friday of November, so 2024-11-29 corresponds to 2025-11-28), the prior-year window may extend beyond your requested
endby up to ±6 days. ThedayOffsetfield on each datapoint reflects the canonical event-offset and is consistent across years.
Response
dayOffset is a signed integer indicating each datapoint's position relative to the event (0 = event day, negative = before, positive = after). It is populated on daily responses and omitted on hourly responses. Use dayOffset for unambiguous year-over-year alignment: for any given offset, currentYearIndex / currentValue and priorYearIndex / priorYearValue represent the same event-relative day in different years.
Field population by mode:
Field
index
brand
brandWithIndex
currentYearIndex
●
●
priorYearIndex
●
●
currentValue
●
●
baselineValue
●
●
priorYearValue
●
●
brandIndex
●
All numeric fields are number | null. A null indicates the underlying brand or index row was missing for that cell (e.g. a brand with no prior-year data).
Rate limits
Uses the same rate limit as the /analytics/sitewide/* endpoints. Aggregated, cacheable data — see the Rate Limiting Reference.
Rate Limit: 10 requests per 30s window, refilling 5 tokens every 30s.
Intelligems external API access token.
Seasonal event identifier. Supported values: "BFCM" (Black Friday / Cyber Monday), "laborDay", "memorialDay", "presidentsDay".
Metric to return. Supported values: "revenue" (net revenue), "orders" (order count), "priceLevels" (average unit price).
How each datapoint's dt is labeled. "actualDate" returns an ISO 8601 datetime; "daysFromEvent" returns a signed integer string (e.g. "-3", "0", "2") relative to the event day.
"hourly" returns one datapoint per hour for the event day (uses the holiday_benchmarking_single_day dataset). "daily" returns one datapoint per day across a range spanning the event (uses holiday_benchmarking_multiple_days).
"index" returns industry-wide index values only (currentYearIndex, priorYearIndex). "brand" returns the caller's brand actuals vs baseline (currentValue, baselineValue, priorYearValue). "brandWithIndex" returns brand actuals plus the brand's own index (brandIndex) and industry index overlays.
Which year of the event to fetch (e.g. 2025 for BFCM 2025). Defaults to the most recently completed occurrence of the event. The prior-year comparison cohort is always year - 1. For hourly granularity, leave this unset or pass a year matching end's year — passing a mismatched year + end will yield nonsensical results.
Required. Start of analysis period as an ISO 8601 datetime string. Used to size the window before the event (days-before-holiday); does not influence which event year is fetched. For hourly granularity, ignored. To match the Intelligems dashboard's Q4 view, pass Oct 1 of the event year (58 days before BFCM).
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$Required. End of analysis period as an ISO 8601 datetime string. Used to size the window after the event (days-after-holiday); does not influence which event year is fetched. For hourly granularity this is interpreted as "the day to analyze" and is expected to fall within year. To match the Intelligems dashboard's Q4 view, pass Dec 31 of the event year (33 days after BFCM).
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$OK
Too Many Requests
curl --location 'https://api.intelligems.io/v25-10-beta/analytics/event/timeseries' \
--header 'content-type: application/json' \
--header 'intelligems-access-token: YOUR_API_KEY' \
--data '{
"event": "BFCM",
"metric": "revenue",
"xAxis": "actualDate",
"granularity": "daily",
"mode": "brandWithIndex",
"start": "2025-10-01T00:00:00.000-05:00",
"end": "2025-12-31T00:00:00.000-05:00"
}'{
"currency": "USD",
"data": [
{
"dt": "2025-11-27T00:00:00Z",
"dayOffset": -1,
"currentValue": 84200.5,
"baselineValue": 61350,
"priorYearValue": 72180.25,
"currentYearIndex": 1.37,
"priorYearIndex": 1.18,
"brandIndex": 1.37
},
{
"dt": "2025-11-28T00:00:00Z",
"dayOffset": 0,
"currentValue": 152980.75,
"baselineValue": 61350,
"priorYearValue": 118420,
"currentYearIndex": 2.49,
"priorYearIndex": 1.93,
"brandIndex": 2.49
},
{
"dt": "2025-11-29T00:00:00Z",
"dayOffset": 1,
"currentValue": 121540,
"baselineValue": 61350,
"priorYearValue": 96310.5,
"currentYearIndex": 1.98,
"priorYearIndex": 1.57,
"brandIndex": 1.98
}
]
}Last updated
Was this helpful?