DayRangePeriod Class

Widening: interpretation of a DayRangePeriod in the context of a Breakdown

If the boundaries of a DayRangePeriod line up neatly with the date splitting of a Breakdown that contains it, then the calculated data will cover the specified range exactly (or a subset of that range if there isn't enough data to satisfy the request fully). This will always be the case if the period is contained within a DailyBreakdown.

If you put a DayRangePeriod inside a WeeklyBreakdown, MonthlyBreakdown, YearlyBreakdown, or FullYearsAverageBreakdown, then it is up to you whether you ensure that the boundaries of your period line up neatly with the weekly/monthly/yearly splitting of the breakdown. If your period specifies dates that do line up with the breakdown, then those dates will be treated as an exact specification. If your period specifies dates that don't line up with the breakdown, the API will effectively widen the range (at the beginning, or the end, or both boundaries if necessary) to ensure that the returned data covers all the dates that your range specifies (assuming enough data exists to do this).

The following examples should help to make this clearer:

Widening example 1

DayRangePeriod period = 
    Period.DayRange(new Day(2025, 2, 19).To(2025, 3, 5));
DatedBreakdown breakdown = DatedBreakdown.Monthly(period);

Dim period As New DayRangePeriod(New Day(2025, 2, 19).To(2025, 3, 5))
Dim breakdown As DatedBreakdown = DatedBreakdown.Monthly(period)

In this example you can see that the dates of the period (2025-02-19 to 2025-03-05) do not match up with the calendar months that the MonthlyBreakdown specifies. In this instance the API would widen the range at both the beginning and the end, attempting to return one monthly value for February 2025 and one for March 2025.

If the first day of the specified period was the first day of a breakdown month (e.g. 2025-02-01), the range would not have been widened at the start. Similarly, if the last day of the specified period was the last day of a breakdown month (e.g. 2025-03-31), the range would not have been widened at the end. Widening only occurs when the dates don't line up with the splitting of the breakdown.

Widening example 2

Day singleDay = new Day(2024, 10, 21);
DayRangePeriod period = Period.DayRange(singleDay.To(singleDay));
DatedBreakdown breakdown = DatedBreakdown.Yearly(period);

Dim singleDay As New Day(2024, 10, 21)
Dim period As New DayRangePeriod(singleDay.To(singleDay))
Dim breakdown As DatedBreakdown = DatedBreakdown.Yearly(period)

In this example the period is specified to cover just one day: 2024-10-21. Of course, that period, if interpreted explicitly, is not long enough to allow a yearly breakdown.

In this instance the API would widen the range at the beginning and the end, giving 2024-01-01 to 2024-12-31, so that it could return a yearly value for 2024 (the year containing the specified range).

Additional notes on widening

• When you create a DayRangePeriod object, that object will always contain the exact dates that you specified. Widening can only happen when those dates are being interpreted as part of the data-assembly process.
• You can use widening to your advantage - passing approximate ranges and relying on the automatic widening can save you some date arithmetic and keep your code simpler.
• Though be careful if you are fetching larger quantities of data and are concerned about rate limits... If, for example, you use an imprecise DayRangePeriod as part of a request for 12 months of monthly data (e.g. calendar months from 2024-01-14 to 2025-01-13), widening could push that to 13 months (e.g. 2024-01-01 to 2025-01-31), pushing you closer towards your rate limit than you would have wanted. This can't happen if you specify your dates precisely or use LatestValuesPeriod instead of DayRangePeriod.

Reference