--- title: "Get holiday benchmark timeseries" method: POST path: "/v25-10-beta/analytics/event/timeseries" tags: ["Get Holiday Benchmark Data"] --- # Get holiday benchmark timeseries `POST /v25-10-beta/analytics/event/timeseries` ## Request - Base URL: `https://api.intelligems.io` - URL: `https://api.intelligems.io/v25-10-beta/analytics/event/timeseries` - Auth: API key in header `intelligems-access-token` - TypeScript: (a function with typed inputs; its response is checked against the schema) 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 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 ```json { "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. **Rate Limit:** 10 requests per 30s window, refilling 5 tokens every 30s. ## Request body - object - `event` 'BFCM' | 'laborDay' | 'memorialDay' | 'presidentsDay', required: Seasonal event identifier. Supported values: "BFCM" (Black Friday / Cyber Monday), "laborDay", "memorialDay", "presidentsDay". - `metric` 'revenue' | 'orders' | 'priceLevels', required: Metric to return. Supported values: "revenue" (net revenue), "orders" (order count), "priceLevels" (average unit price). - `xAxis` 'actualDate' | 'daysFromEvent', required: 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. - `granularity` 'hourly' | 'daily', required: "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). - `mode` 'index' | 'brand' | 'brandWithIndex', required: "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. - `year` integer: 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. - `start` string, date-time, required: 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). - `end` string, date-time, required: 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). ## Response `200` OK - object - `currency` string, required: ISO 4217 currency code for monetary values (e.g. 'USD'). - `data` object[], required: Array of datapoints indexed by `dt`. Each entry may populate a subset of value fields depending on the requested `mode`. - `dt` string, required: Datapoint label — an ISO 8601 datetime (when xAxis='actualDate') or a signed day offset as a string (when xAxis='daysFromEvent'). - `dayOffset` integer: Signed integer event-offset for this datapoint (0 = event day, negative = before, positive = after). Present on daily-granularity responses; omitted on hourly responses. - `currentValue` number, nullable: Brand actual value for the selected metric during the current event year. Populated when mode is 'brand' or 'brandWithIndex'. - `baselineValue` number, nullable: Brand typical-day baseline value for the selected metric. Populated when mode is 'brand' or 'brandWithIndex'. - `priorYearValue` number, nullable: Brand actual value for the selected metric during the prior event year. Populated when mode is 'brand' or 'brandWithIndex'. - `currentYearIndex` number, nullable: Industry-wide index value (percent of full-day baseline) for the current event year. Populated when mode is 'index' or 'brandWithIndex'. - `priorYearIndex` number, nullable: Industry-wide index value for the prior event year. Populated when mode is 'index' or 'brandWithIndex'. - `brandIndex` number, nullable: The brand's own value expressed as a percent of its full-day baseline. Populated when mode is 'brandWithIndex'. ## Other responses - `429`: Too Many Requests --- [API](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta.md) - [All operations](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta/llms.txt) - [OpenAPI document](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta/revisions/7b769b2f90b1?raw)