08 Get Holiday Benchmark Data

post

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

Field	Required	Type	Notes
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

{
  "currency": "USD",
  "snapshot": {
    "periodToDateValue": 125000.5,
    "vsLastYear": 0.12,
    "avgDailyIndexPercent": 1.27,
    "currentIndexPercent": 1.23
  }
}

• 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.

Authorizations

intelligems_access_token

intelligems-access-tokenstringRequired

Intelligems external API access token.

Body

application/json

eventstring · enumRequired

Seasonal event identifier. Supported values: "BFCM" (Black Friday / Cyber Monday), "laborDay", "memorialDay", "presidentsDay".

Possible values:

metricstring · enumRequired

Metric to return. Supported values: "revenue" (net revenue), "orders" (order count), "priceLevels" (average unit price).

Possible values:

yearinteger · min: 2021 · max: 2026Optional

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.

startstring · date-timeRequired

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).

Pattern: ^(?:(?:\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)))$

endstring · date-timeRequired

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).

Pattern: ^(?:(?:\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)))$

Responses

200

OK

application/json

post

/v25-10-beta/analytics/event/snapshot

BFCM brand snapshot (revenue, Q4 window — matches dashboard "Q4 to Date" tile)Memorial Day brand snapshot (orders)

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"
}'

200

OK

{
  "currency": "text",
  "snapshot": {
    "periodToDateValue": 1,
    "vsLastYear": 1,
    "avgDailyIndexPercent": 1,
    "currentIndexPercent": 1
  }
}

post

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

Field	Required	Type	Notes
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 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 end by up to ±6 days. The dayOffset field on each datapoint reflects the canonical event-offset and is consistent across years.

Response

{
  "currency": "USD",
  "data": [
    {
      "dt": "2025-11-26T00:00:00",
      "dayOffset": -2,
      "currentValue": 5200.15,
      "baselineValue": 4100.0,
      "priorYearValue": 4800.5,
      "currentYearIndex": 1.27,
      "priorYearIndex": 1.19,
      "brandIndex": 1.27
    }
  ]
}

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.

Authorizations

intelligems_access_token

intelligems-access-tokenstringRequired

Intelligems external API access token.

Body

application/json

eventstring · enumRequired

Seasonal event identifier. Supported values: "BFCM" (Black Friday / Cyber Monday), "laborDay", "memorialDay", "presidentsDay".

Possible values:

metricstring · enumRequired

Metric to return. Supported values: "revenue" (net revenue), "orders" (order count), "priceLevels" (average unit price).

Possible values:

xAxisstring · enumRequired

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.

Possible values:

granularitystring · enumRequired

"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).

Possible values:

modestring · enumRequired

"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.

Possible values:

yearinteger · min: 2021 · max: 2026Optional

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.

startstring · date-timeRequired

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).

Pattern: ^(?:(?:\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)))$

endstring · date-timeRequired

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).

Pattern: ^(?:(?:\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)))$

Responses

200

OK

application/json

post

/v25-10-beta/analytics/event/timeseries

BFCM daily brand + index overlay (revenue, Q4 window)BFCM index-only daily chart (orders, daysFromEvent axis, Q4 window)BFCM hourly brand benchmark (price levels, single day)Custom date range (Labor Day, 7 days before and 3 days after)Presidents Day index-only timeseries (priceLevels)

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"
}'

200

OK

{
  "currency": "text",
  "data": [
    {
      "dt": "text",
      "dayOffset": 1,
      "currentValue": 1,
      "baselineValue": 1,
      "priorYearValue": 1,
      "currentYearIndex": 1,
      "priorYearIndex": 1,
      "brandIndex": 1
    }
  ]
}