Periods & dates

Every query needs a period — the window of time it covers. There are two ways to express it, plus two ways to shape the resulting series (moving average and resampling).

Dates: absolute vs relative

A date is either absolute (a fixed calendar date) or relative (a number of units before today, so the window moves forward as time passes).

Absolute:

{ "date": "2024-01-01" }

Relative — any combination of days, weeks, months, years, measured backwards from today:

{ "days": 90 }

Start / end period

Provide a start_date and an end_date. Each can be absolute or relative, and you may mix them:

{
  "start_date": { "date": "2024-01-01" },
  "end_date":   { "days": 5 }
}

Common patterns:

• Rolling window — relative start + relative end (e.g. "the last 90 days").
• Since a fixed point — absolute start + relative end (e.g. "since launch, up to recent").

Offset period ("last month", "last week")

An offset period expresses a self-updating window in natural units:

Field	Required	Default	Meaning
type	Yes	—	The unit: week, semi_month, month, quarter, semi_year, year.
offset	Yes	—	How many units back the window ends (1 = the most recent complete unit).
amount	Yes	—	How many units the window spans.
adjust_by	No	none	A relative date used to push the window further back.
starting_month	No	1	For quarter/year units, the month the year is treated as starting in (e.g. a fiscal year).
starting_weekday	No	sunday	For week units, which day the week starts on.

"The last complete month":

{ "type": "month", "offset": 1, "amount": 1 }

"The last three complete months":

{ "type": "month", "offset": 1, "amount": 3 }

day appears in the OpenAPI spec's PeriodType enum but is not currently supported — requests using it fail. Use a relative start/end date for day-granular windows instead.

Validation rules

The service rejects periods that cannot resolve to a valid, stable window:

• The end date must not be earlier than the start date.
• You cannot combine a relative start with an absolute end — that window would eventually become invalid as time moves on.
• Relative dates that resolve to the future are rejected.
• For offset periods: amount ≥ 1, offset ≥ 0, and amount ≤ offset + 1 (you cannot request more history than the offset reaches back to).
• The latest available day is always "yesterday"; requests never run past the most recent complete day of data.

Shaping the series

Moving average

A rolling mean applied across the series, in days. 1 (the default) means no smoothing. Leading days before your start date are pulled in as needed, so the first data point already reflects a full window rather than ramping up.

"moving_average": 30

The BrandIndex UI offers moving averages from 3 days to 52 weeks; the API takes the window as a plain number of days.

Resampling

Groups results into larger buckets instead of native daily granularity:

"resample": { "size": 1, "type": "month_from_day" }

type is a frequency type, not a plain unit name — "month", "quarter" and "year" are not valid values. The _from_day types anchor buckets to your period's start date; the full list (including calendar-anchored variants such as month_start and month_end) is the FrequencyType enum in the interactive reference. The recipes matching the BrandIndex UI's periodicities:

size / type	Result
7 / calendar_day	Weekly
28 / calendar_day	4-weekly
1 / month_from_day	Monthly
1 / quarter_from_day	Quarterly
6 / month_from_day	Half-yearly
1 / year_from_day	Yearly
1 / match_period	A single bucket spanning the whole period

If both are set, resample takes precedence and moving_average is ignored — they are alternative ways of aggregating.

Related

• Execute an analysis
• Request size & limits