Get holiday benchmark timeseries

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

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 daily window. For granularity: "daily" the returned range is always widened to reach the event day, so the effective window is [min(start, eventDay), max(end, eventDay)]. Requesting start and end that 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), start 2025-12-20T00:00:00Z / end 2025-12-25T00:00:00Z returns 28 datapoints beginning 2025-11-28, and start 2025-10-01T00:00:00Z / end 2025-10-10T00:00:00Z returns 59 datapoints ending 2025-11-28. Filter on dayOffset or dt client-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 end of 2025-12-05T23:59:59Z yields a final dt of 2025-12-06T00:00:00. That rounding adds a datapoint, so it compounds with the widening above — the first example sent with end 2025-12-25T23:59:59Z instead of 2025-12-25T00:00:00Z returns 29 datapoints, through dt 2025-12-26T00:00:00 (dayOffset 0 through 28). Both counts are correct; pass a day-aligned end when 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 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:

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.