TimeSeriesDataSpec Class

A TimeSeriesDataSpec specifies a set of time-series data in terms of:

• the calculation process used to calculate the time-series figures (see the remarks for TimeSeriesCalculation to find out why time-series data is "calculated"); and
• a breakdown that determines the period in time that the time-series data should cover (more on this below).

Example TimeSeriesDataSpec code:

Here's how you could specify hourly temperature data, in Fahrenheit, covering the last 30 days:

TimeSeriesDataSpec timeSeriesDataSpec = DataSpec.TimeSeries(
    TimeSeriesCalculation.HourlyTemperature(TemperatureUnit.Fahrenheit),
    DatedBreakdown.Daily(Period.LatestValues(30)));

Dim timeSeriesDataSpec As TimeSeriesDataSpec = DataSpec.TimeSeries(
    TimeSeriesCalculation.HourlyTemperature(TemperatureUnit.Fahrenheit),
    DatedBreakdown.Daily(Period.LatestValues(30)))

You could then send that TimeSeriesDataSpec to the API as part of a LocationDataRequest, and get a response containing a TimeSeriesDataSet back:

DegreeDaysApi api = new DegreeDaysApi(new AccountKey(yourStringAccountKey),
    new SecurityKey(yourStringSecurityKey));
LocationDataRequest request = new LocationDataRequest(
    Location.PostalCode("02630", "US"),
    new DataSpecs(timeSeriesDataSpec));
LocationDataResponse response = api.DataApi.GetLocationData(request);
TimeSeriesDataSet hourlyData = 
    response.DataSets.GetTimeSeries(timeSeriesDataSpec);
foreach (TimeSeriesDataValue v in hourlyData.Values) {
    Console.WriteLine(v.DateTimeOffset + ": " + v.Value);
}

Dim api As DegreeDaysApi = New DegreeDaysApi(New AccountKey(yourStringAccountKey),
    New SecurityKey(yourStringSecurityKey))
Dim request As LocationDataRequest = New LocationDataRequest(
    Location.PostalCode("02630", "US"),
    New DataSpecs(timeSeriesDataSpec))
Dim response As LocationDataResponse = api.DataApi.GetLocationData(request)
Dim hourlyData As TimeSeriesDataSet = 
    response.DataSets.GetTimeSeries(timeSeriesDataSpec)
For Each v As TimeSeriesDataValue In hourlyData.Values
    Console.WriteLine(v.DateTimeOffset.ToString() & ": " & v.Value)
Next

To include figures for the current day (as opposed to the default behaviour of covering full days only), you can specify a DatedBreakdown with its AllowPartialLatest property set to true. For example:

TimeSeriesDataSpec hourlyTempsIncludingToday = DataSpec.TimeSeries(
    TimeSeriesCalculation.HourlyTemperature(TemperatureUnit.Fahrenheit),
    DatedBreakdown.Daily(Period.LatestValues(31))
        .WithAllowPartialLatest(true));

Dim hourlyTempsIncludingToday As TimeSeriesDataSpec = DataSpec.TimeSeries(
    TimeSeriesCalculation.HourlyTemperature(TemperatureUnit.Fahrenheit),
    DatedBreakdown.Daily(Period.LatestValues(31)) _
        .WithAllowPartialLatest(True))

The docs for AllowPartialLatest explain more, including an important caution that the latest figures can be volatile, and, if stored, should be overwritten later when the weather stations have had time to send any delayed or corrected weather reports (which many weather stations send quite often).

Why does TimeSeriesDataSpec take a DatedBreakdown?

It might seem strange that TimeSeriesDataSpec takes a DatedBreakdown in the same way that DatedDataSpec (for degree days) does, because hourly data is broken down hourly, not by days, weeks, or months. However, it works this way to give you flexibility in how you specify the time-period that the time-series data should cover, and to make it easier for you to get time-series data that lines up with your degree days.

With a DatedBreakdown you can easily specify that you want hourly data covering e.g. the last 30 days, or the last 12 full calendar months, or the last 5 full calendar years, just like you do when you are using a DatedBreakdown to specify the degree days you want. You can take full advantage of widening rules if they make things more convenient for you. The data will always come back as hourly figures. Essentially a daily, weekly, monthly, or yearly breakdown in a TimeSeriesDataSpec is used only to determine the overall period of time that the time-series data should cover.

Custom breakdowns deserve a special note, however... If you create a TimeSeriesDataSpec with a custom breakdown (made up of your own custom-specified DayRanges), then your time-series data will cover only the day ranges you specify. If you specify day ranges with gaps between them, then your time-series data will have gaps too (just as your degree days would if you used the same breakdown for them). This is rather contrary to our general ethos of providing continuous data with no gaps, but it will only happen if you specifically request it (by specifying a custom breakdown with gaps between its day ranges).

Reference