degreedays.api.data.impl - Degree Days.net API Python Client Library

class degreedays.api.data.impl.CoolingDegreeDaysCalculation(baseTemperature: Temperature)¶

A type of Calculation that specifies that cooling degree days should be calculated and that holds the base temperature that they should be calculated to.

Parameters:: baseTemperature (Temperature) – the base temperature that the cooling degree days should be calculated to.
Raises:: TypeError – if baseTemperature is not a Temperature object.

property baseTemperature: Temperature¶: The base temperature of the cooling-degree-days calculation.

class degreedays.api.data.impl.CustomBreakdown(dayRanges: DayRanges, allowPartialLatest: bool = False)¶

A type of DatedBreakdown used to specify that degree days should be broken down into the custom date ranges specified e.g. to match the dates of your energy-usage records.

Parameters:

dayRanges (DayRanges) – specifying the dates that each degree-day figure should cover (typically matching the dates of your energy-usage records).
allowPartialLatest (bool) – True to specify that the latest specified day range can be partially filled (i.e. incomplete), or False if it must be complete (the default behaviour). Setting this to True is mainly useful if you are fetching time-series data (via TimeSeriesDataSpec) and you want it to include values for the current (incomplete) day. See allowPartialLatest for more on this.

Raises:

TypeError – if dayRanges is not a degreedays.time.DayRanges object, or if allowPartialLatest is not a bool.

property allowPartialLatest: bool¶

True if the latest day range can be partially filled (i.e. incomplete); False otherwise (the default case).

When specifying time-series data (like hourly temperature data) via a TimeSeriesDataSpec, you can specify a breakdown with this allowPartialLatest property set to True, to tell the API to include values for the current day so far. For example:

hourlyTempsIncludingToday = DataSpec.timeSeries(
    TimeSeriesCalculation.hourlyTemperature(TemperatureUnit.CELSIUS),
    DatedBreakdown.daily(Period.latestValues(31), allowPartialLatest=True))

If you requested the above-specified hourly temperature data at, say, 11:42 on any given day, you could expect it to include values for 00:00, 01:00, 02:00 through to 11:00 on that day (bearing in mind that some stations are slower to report than others so you won’t always get the absolute latest figures).

Please note that the most recent time-series data can be a little volatile, as weather stations sometimes send multiple reports for the same time, some delayed, and some marked as corrections for reports they sent earlier. Our system generates time-series data using all the relevant reports that each weather station has sent, but the generated figures may change if delayed or corrected reports come through later. If you are storing partial-latest time-series data we suggest you overwrite it later with figures generated after the day has completed and any delayed/corrected reports have had time to filter through.

This allowPartialLatest property exists mainly for time-series data, but you can also set it to True on a breakdown for degree days, to specify that the data can include a value for the latest partial week/month/year. For example:

monthlyHddIncludingPartialLatest = DataSpec.dated(
    Calculation.heatingDegreeDays(Temperature.fahrenheit(65)),
    DatedBreakdown.monthly(Period.latestValues(12), allowPartialLatest=True))

If you requested the above-specified monthly degree-day data on, say, June 22nd, you could expect the last of the 12 values returned to cover from the start of June 1st through to the end of June 21st (assuming a good weather station with frequent reporting and minimal delays). If you left allowPartialLatest with its default value of False, the last of the 12 values returned would be for the full month of May (i.e. from the start of May 1st to the end of May 31st), as the monthly figure for June wouldn’t become available until June ended.

Unlike for time-series data (specified with TimeSeriesDataSpec), this property will never cause degree days to be calculated for partial days. So for degree days this property will only make a difference on weekly, monthly, yearly, and custom breakdowns with day ranges covering multiple days.

Any partial-latest day range will always start on the usual day (i.e. it will never be cut short at the start), it’s only the end that can be cut short. This is true for both degree days and time-series data.

property dayRanges: DayRanges¶: The degreedays.time.DayRanges that specifies the dates that each degree-day figure should cover.

class degreedays.api.data.impl.DailyBreakdown(period: Period, allowPartialLatest: bool = False)¶

A type of DatedBreakdown used to specify that degree days should be broken down on a daily basis and cover a specific Period in time.

Parameters:

period (Period) – the period in time that the daily breakdown should cover.
allowPartialLatest (bool) – True to specify that the latest day of data can be partially filled (i.e. incomplete), or False if the latest day must be complete (the default behaviour). Setting this to True is mainly useful if you are fetching time-series data (via TimeSeriesDataSpec) and you want it to include values for the current (incomplete) day. See allowPartialLatest for more on this.

Raises:

TypeError – if period is not a Period object, or allowPartialLatest is not a bool.

property allowPartialLatest: bool¶

True if the latest day range can be partially filled (i.e. incomplete); False otherwise (the default case).

When specifying time-series data (like hourly temperature data) via a TimeSeriesDataSpec, you can specify a breakdown with this allowPartialLatest property set to True, to tell the API to include values for the current day so far. For example:

hourlyTempsIncludingToday = DataSpec.timeSeries(
    TimeSeriesCalculation.hourlyTemperature(TemperatureUnit.CELSIUS),
    DatedBreakdown.daily(Period.latestValues(31), allowPartialLatest=True))

If you requested the above-specified hourly temperature data at, say, 11:42 on any given day, you could expect it to include values for 00:00, 01:00, 02:00 through to 11:00 on that day (bearing in mind that some stations are slower to report than others so you won’t always get the absolute latest figures).

Please note that the most recent time-series data can be a little volatile, as weather stations sometimes send multiple reports for the same time, some delayed, and some marked as corrections for reports they sent earlier. Our system generates time-series data using all the relevant reports that each weather station has sent, but the generated figures may change if delayed or corrected reports come through later. If you are storing partial-latest time-series data we suggest you overwrite it later with figures generated after the day has completed and any delayed/corrected reports have had time to filter through.

This allowPartialLatest property exists mainly for time-series data, but you can also set it to True on a breakdown for degree days, to specify that the data can include a value for the latest partial week/month/year. For example:

monthlyHddIncludingPartialLatest = DataSpec.dated(
    Calculation.heatingDegreeDays(Temperature.fahrenheit(65)),
    DatedBreakdown.monthly(Period.latestValues(12), allowPartialLatest=True))

If you requested the above-specified monthly degree-day data on, say, June 22nd, you could expect the last of the 12 values returned to cover from the start of June 1st through to the end of June 21st (assuming a good weather station with frequent reporting and minimal delays). If you left allowPartialLatest with its default value of False, the last of the 12 values returned would be for the full month of May (i.e. from the start of May 1st to the end of May 31st), as the monthly figure for June wouldn’t become available until June ended.

Unlike for time-series data (specified with TimeSeriesDataSpec), this property will never cause degree days to be calculated for partial days. So for degree days this property will only make a difference on weekly, monthly, yearly, and custom breakdowns with day ranges covering multiple days.

Any partial-latest day range will always start on the usual day (i.e. it will never be cut short at the start), it’s only the end that can be cut short. This is true for both degree days and time-series data.

property period: Period¶: The period in time that the daily breakdown should cover.

class degreedays.api.data.impl.DayRangePeriod(dayRange: DayRange, minimumDayRangeOrNone: DayRange | None = None)¶

A type of Period that is defined explicitly in terms of the range of days that it covers.

Parameters:

dayRange (degreedays.time.DayRange) – the range of days that the period should cover.
minimiumDayRangeOrNone (degreedays.time.DayRange | None) – you can specify this if you would rather have a failure than a partial set of data covering less than your specified minimum range. Otherwise you may get back less data than you asked for if there aren’t enough weather-data records to generate a full set for your specified location. See minimumDayRangeOrNone for more on this.

Raises:

TypeError – if dayRange is not a degreedays.time.DayRange, or if minimumDayRangeOrNone is not a degreedays.time.DayRange or None.
ValueError – if minimumDayRangeOrNone is a degreedays.time.DayRange that extends earlier or later than dayRange.

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¶

period = Period.dayRange(degreedays.time.DayRange(
        datetime.date(2025, 2, 19), datetime.date(2025, 3, 5)))
breakdown = 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¶

singleDay = datetime.date(2024, 10, 21)
period = Period.dayRange(degreedays.time.DayRange(singleDay, singleDay))
breakdown = 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.

property dayRange: DayRange¶: The degreedays.time.DayRange object that specifies the day(s) that this period covers.

property minimumDayRangeOrNone: DayRange | None¶

The minimium day range the API must cover if it is able to generate data within this DayRangePeriod, or None if no such minimum is specified.

If this is None, the API can decide what to do if there is not enough data available to satisfy the dayRange, and it will typically return what it can from within dayRange. If a minimum day range is set, then a request for data will fail unless that minimum range can be satisfied.

Warning: be careful with minimum ranges, particularly when defining the last day of a minimum range. The degree days for any given day will never become available until the day has finished in the location’s local time-zone, and will always take at least a little longer (and sometimes quite a lot longer) for the reasons explained here. If your system specifies a minimum range that is too restrictive, it can easily end up with no data at all when in fact there’s plenty of usable data available.

That said, there are times when a minimum range with highly-restrictive dates is exactly what you want (and you’d rather get nothing than slightly less data), so don’t be afraid to specify restrictive minimum ranges if you need them.

class degreedays.api.data.impl.FullYearsAverageBreakdown(period: Period)¶

A type of AverageBreakdown used to specify that average-degree-day figures should be derived from data covering a specified number of full calendar years.

Parameters:: period (Period) – specifies the full calendar years of data that the average figures should be derived from. Typically you’d want to use Period.latestValues for this, specifying at least 2 values (since an average of 1 year of data is not very meaningful). But you can also use Period.dayRange - in this case the period may be widened for calculation purposes to make it cover full calendar years.
Raises:: TypeError – if period is not a Period object.

The years used will always be consecutive (i.e. no gaps), and are specified using the Period passed into the constructor.

Typically you’d want to use Period.latestValues to create the Period, to specify that the last year of the average should be the most recent full calendar year.

If you want average data calculated using a different method, remember that you can always fetch dated data and calculate averages directly from that.

property period: Period¶: The period in time that the breakdown should average data from.

class degreedays.api.data.impl.HeatingDegreeDaysCalculation(baseTemperature: Temperature)¶

A type of Calculation that specifies that heating degree days should be calculated and that holds the base temperature that they should be calculated to.

Parameters:: baseTemperature (Temperature) – the base temperature that the heating degree days should be calculated to.
Raises:: TypeError – if baseTemperature is not a Temperature object.

property baseTemperature: Temperature¶: The base temperature of the heating-degree-days calculation.

class degreedays.api.data.impl.LatestValuesPeriod(numberOfValues: int, minimumNumberOfValuesOrNone: int | None = None)¶

A type of Period that automatically resolves to a date range including the latest available data and the specified number of degree-day values.

Parameters:

numberOfValues (int) – a number, greater than zero, that specifies how many degree-day values the period should cover (see below for an explanation of how the values in question can be daily, weekly, monthly, or yearly). This is effectively an upper bound: if there isn’t enough good data to cover the numberOfValues specified, the API will assemble and return what it can.
minimumNumberOfValuesOrNone (int | None) – you can specify this if you would rather have a failure than a partial set of data with less than your specified minimum number of values. Otherwise you may get back less data than you asked for if there aren’t enough weather-data records to generate a full set for your specified location.

Raises:

TypeError – if numberOfValues is not an int, or if minimumNumberOfValuesOrNone is not an int or None.
ValueError – if numberOfValues is less than 1, or if minimumNumberOfValuesOrNone is an int that is less than 1 or greater than numberOfValues.

The meaning of the specified number of values depends on the type of the Breakdown that holds this period. For example, if you create a LatestValuesPeriod specifying x values then:

Used as the Period in a DailyBreakdown it would specify the x most recent days of data.
Used as the Period in a WeeklyBreakdown it would specify the x most recent weeks of data.
Used as the Period in a MonthlyBreakdown it would specify the x most recent months of data.
Used as the Period in a YearlyBreakdown it would specify the x most recent years of data.
Used as the Period in a FullYearsAverageBreakdown it would specify the x most recent full calendar years of data.

If you want data covering specific dates, you may be better off using a DayRangePeriod. But this class can be a useful convenience if you want the latest available data containing a specific number of daily, weekly, monthly, or yearly values. It can save you from some date arithmetic, and you won’t need to consider the time-zones or update delays of the weather stations that you’re getting data from to figure out the exact dates of the latest data that is likely to be available.

property minimumNumberOfValuesOrNone: int | None¶

The minimium number of values, greater than zero, that the API must include to provide data to the specification of this LatestValuesPeriod, or None if no such minimum number is specified.

If this is None, the API can decide what to do if there is not enough data available to satisfy the numberOfValues requested, and it will typically return as many values as it can. If a minimum number of values is specified, then a request for data will fail unless that minimum number of values can be satisfied.

property numberOfValues: int¶: A number, greater than zero, indicating how many degree-day values this period should cover (the values in question can be daily, weekly, monthly, or yearly, depending on the type of the Breakdown that holds this period).

class degreedays.api.data.impl.LongLatLocation(longLat: LongLat)¶

Specifies a location in terms of longitude and latitude coordinates. The API will hunt for a weather station near the specified location that is able to supply the requested data, or it might (at some point) average data from multiple weather stations around the specified location if it thinks that might significantly improve results.

Parameters:: longLat (LongLat) – the longitude/latitude position.
Raises:: TypeError – if longLat is not a degreedays.geo.LongLat object.

Make sure to specify the full range of data that you want when using this location type - some weather stations have less data than others so it’s important for the API to have the full range when it’s choosing which station(s) to use. The LocationDataResponse will include an station ID that will enable you to fetch new data calculated from the same weather station(s) used by the API initially.

See also: GeographicLocation

property longLat: LongLat¶: The longitude/latitude position of this LongLatLocation.

class degreedays.api.data.impl.MonthlyBreakdown(period: Period, startOfMonth: StartOfMonth = StartOfMonth(1), allowPartialLatest: bool = False)¶

A type of DatedBreakdown used to specify that degree days should be broken down on a monthly basis and cover a specific Period in time.

Parameters:

period (Period) – the period in time that the monthly breakdown should cover.
startOfMonth (StartOfMonth) – specifying which day (between 1 and 28 inclusive) should be taken as the first of each “month”. StartOfMonth(1) is the default value and specifies regular calendar months.
allowPartialLatest (bool) – True to specify that the latest month of data can be partially filled (i.e. incomplete), or False if the latest month must be complete (the default behaviour). Setting this to True is mainly useful if you are fetching time-series data (via TimeSeriesDataSpec) and you want it to include the current (incomplete) month, including values for the current (incomplete) day. See allowPartialLatest for more on this.

Raises:

TypeError – if period is not a Period object, or if startOfMonth is not a degreedays.time.StartOfMonth object, or if allowPartialLatest is not a bool.

property allowPartialLatest: bool¶

True if the latest day range can be partially filled (i.e. incomplete); False otherwise (the default case).

When specifying time-series data (like hourly temperature data) via a TimeSeriesDataSpec, you can specify a breakdown with this allowPartialLatest property set to True, to tell the API to include values for the current day so far. For example:

hourlyTempsIncludingToday = DataSpec.timeSeries(
    TimeSeriesCalculation.hourlyTemperature(TemperatureUnit.CELSIUS),
    DatedBreakdown.daily(Period.latestValues(31), allowPartialLatest=True))

If you requested the above-specified hourly temperature data at, say, 11:42 on any given day, you could expect it to include values for 00:00, 01:00, 02:00 through to 11:00 on that day (bearing in mind that some stations are slower to report than others so you won’t always get the absolute latest figures).

Please note that the most recent time-series data can be a little volatile, as weather stations sometimes send multiple reports for the same time, some delayed, and some marked as corrections for reports they sent earlier. Our system generates time-series data using all the relevant reports that each weather station has sent, but the generated figures may change if delayed or corrected reports come through later. If you are storing partial-latest time-series data we suggest you overwrite it later with figures generated after the day has completed and any delayed/corrected reports have had time to filter through.

This allowPartialLatest property exists mainly for time-series data, but you can also set it to True on a breakdown for degree days, to specify that the data can include a value for the latest partial week/month/year. For example:

monthlyHddIncludingPartialLatest = DataSpec.dated(
    Calculation.heatingDegreeDays(Temperature.fahrenheit(65)),
    DatedBreakdown.monthly(Period.latestValues(12), allowPartialLatest=True))

If you requested the above-specified monthly degree-day data on, say, June 22nd, you could expect the last of the 12 values returned to cover from the start of June 1st through to the end of June 21st (assuming a good weather station with frequent reporting and minimal delays). If you left allowPartialLatest with its default value of False, the last of the 12 values returned would be for the full month of May (i.e. from the start of May 1st to the end of May 31st), as the monthly figure for June wouldn’t become available until June ended.

Unlike for time-series data (specified with TimeSeriesDataSpec), this property will never cause degree days to be calculated for partial days. So for degree days this property will only make a difference on weekly, monthly, yearly, and custom breakdowns with day ranges covering multiple days.

Any partial-latest day range will always start on the usual day (i.e. it will never be cut short at the start), it’s only the end that can be cut short. This is true for both degree days and time-series data.

property period: Period¶: The period in time that the monthly breakdown should cover.

property startOfMonth: StartOfMonth¶: The degreedays.time.StartOfMonth object indicating which day should be taken as the first of each month (inclusive).

class degreedays.api.data.impl.PostalCodeLocation(postalCode: str, countryCode: str)¶

Specifies a location using a postal code (or zip code, post code, or postcode - the terminology depends on the country). The API servers will attempt to find the longitude/latitude location of the specified postal code, and from that point on will treat the location as if it were a LongLatLocation (see the notes for that class for more relevant information).

Parameters:

postalCode (str) – the postal code (or zip code, post code, or postcode) of the location you want data for. Cannot be empty, cannot be longer than 16 characters (a length that we believe allows for all current postal codes worldwide), and cannot contain any characters other than [- 0-9a-zA-Z].
countryCode (str) – the ISO 3166-1-alpha-2 country code of the country that postalCode belongs to. It must be a two-character string comprised of only characters A-Z (i.e. upper case only). For example, pass “US” if postalCode is a US zip code, pass “GB” (for “Great Britain”) if postalCode is a UK post code, and pass “CA” if postalCode is a Canadian zip code.

Raises:

TypeError – if postalCode or countryCode is not a str.
ValueError – if tests indicate that postalCode or countryCode fails to match the specifications detailed above.

property countryCode: str¶: The two-letter upper-case ISO 3166-1-alpha-2 country code of the country that the postal code belongs to.

property postalCode: str¶: The non-empty postal code (or zip code, post code, or postcode - the terminology depends on the country).

class degreedays.api.data.impl.StationIdLocation(stationId: str)¶

Specifies a location in terms of a weather station ID (you can find these IDs through the website at www.degreedays.net or by requesting data for GeographicLocation types).

Parameters:

stationId (str) – the ID of the weather station that the StationIdLocation should represent (i.e. the station you want data for). Cannot be empty, cannot contain contain any characters other than [-_0-9a-zA-Z], and cannot contain more than 60 characters (a limit that is significantly larger than the length of any station ID that we are currently aware of, but that is set high to allow for “virtual station IDs” to be introduced in the future, combining data from multiple stations).

Raises:

TypeError – if stationId is not a str.
ValueError – if tests indicate that stationId fails to match the specification detailed above.

property stationId: str¶: The non-empty string ID of the weather station that this StationIdLocation represents.

class degreedays.api.data.impl.TemperatureTimeSeriesCalculation(interval: TimeSeriesInterval, temperatureUnit: TemperatureUnit)¶

A type of TimeSeriesCalculation that specifies that temperature data should be calculated with the specified interval (e.g. hourly) and unit (e.g. Celsius).

Parameters:: temperatureUnit (TemperatureUnit) – specifies whether the data should be calculated in Celsius or Fahrenheit.
Raises:: TypeError – if temperatureUnit is not a TemperatureUnit object.

Find out why time-series data is “calculated”.

property interval: TimeSeriesInterval¶: The TimeSeriesInterval indicating the interval (e.g. hourly) that the time-series data should be calculated with.

property temperatureUnit: TemperatureUnit¶: The TemperatureUnit indicating whether the temperatures should be calculated in Celsius or Fahrenheit.

class degreedays.api.data.impl.WeeklyBreakdown(period: Period, firstDayOfWeek: DayOfWeek, allowPartialLatest: bool = False)¶

A type of DatedBreakdown used to specify that degree days should be broken down on a weekly basis and cover a specific Period in time, with weeks starting on a specific day of the week.

Parameters:

period (Period) – the period in time that the weekly breakdown should cover.
firstDayOfWeek (DayOfWeek) – indicates which day should be taken as the first of each week.
allowPartialLatest (bool) – True to specify that the latest week of data can be partially filled (i.e. incomplete), or False if the latest week must be complete (the default behaviour). Setting this to True is mainly useful if you are fetching time-series data (via TimeSeriesDataSpec) and you want it to include the current (incomplete) week, including values for the current (incomplete) day. See allowPartialLatest for more on this.

Raises:

TypeError – if period is not a Period object, or if firstDayOfWeek is not a degreedays.time.DayOfWeek object, or if allowPartialLatest is not a bool.

property allowPartialLatest: bool¶

True if the latest day range can be partially filled (i.e. incomplete); False otherwise (the default case).

When specifying time-series data (like hourly temperature data) via a TimeSeriesDataSpec, you can specify a breakdown with this allowPartialLatest property set to True, to tell the API to include values for the current day so far. For example:

hourlyTempsIncludingToday = DataSpec.timeSeries(
    TimeSeriesCalculation.hourlyTemperature(TemperatureUnit.CELSIUS),
    DatedBreakdown.daily(Period.latestValues(31), allowPartialLatest=True))

If you requested the above-specified hourly temperature data at, say, 11:42 on any given day, you could expect it to include values for 00:00, 01:00, 02:00 through to 11:00 on that day (bearing in mind that some stations are slower to report than others so you won’t always get the absolute latest figures).

Please note that the most recent time-series data can be a little volatile, as weather stations sometimes send multiple reports for the same time, some delayed, and some marked as corrections for reports they sent earlier. Our system generates time-series data using all the relevant reports that each weather station has sent, but the generated figures may change if delayed or corrected reports come through later. If you are storing partial-latest time-series data we suggest you overwrite it later with figures generated after the day has completed and any delayed/corrected reports have had time to filter through.

This allowPartialLatest property exists mainly for time-series data, but you can also set it to True on a breakdown for degree days, to specify that the data can include a value for the latest partial week/month/year. For example:

monthlyHddIncludingPartialLatest = DataSpec.dated(
    Calculation.heatingDegreeDays(Temperature.fahrenheit(65)),
    DatedBreakdown.monthly(Period.latestValues(12), allowPartialLatest=True))

If you requested the above-specified monthly degree-day data on, say, June 22nd, you could expect the last of the 12 values returned to cover from the start of June 1st through to the end of June 21st (assuming a good weather station with frequent reporting and minimal delays). If you left allowPartialLatest with its default value of False, the last of the 12 values returned would be for the full month of May (i.e. from the start of May 1st to the end of May 31st), as the monthly figure for June wouldn’t become available until June ended.

Unlike for time-series data (specified with TimeSeriesDataSpec), this property will never cause degree days to be calculated for partial days. So for degree days this property will only make a difference on weekly, monthly, yearly, and custom breakdowns with day ranges covering multiple days.

Any partial-latest day range will always start on the usual day (i.e. it will never be cut short at the start), it’s only the end that can be cut short. This is true for both degree days and time-series data.

property firstDayOfWeek: DayOfWeek¶: The day of the week that should be the first of each weekly period.

property period: Period¶: The period in time that the weekly breakdown should cover.

class degreedays.api.data.impl.YearlyBreakdown(period: Period, startOfYear: StartOfYear = StartOfYear(1, 1), allowPartialLatest: bool = False)¶

A type of DatedBreakdown used to specify that degree days should be broken down on a yearly (annual) basis and cover a specific Period in time.

Parameters:

period (Period) – the period in time that the yearly breakdown should cover.
startOfYear (StartOfYear) – specifying which day of the year (month and day of the month) should be taken as the first of each “year”. StartOfYear(1, 1) is the default value and specifies regular calendar years.
allowPartialLatest (bool) – True to specify that the latest year of data can be partially filled (i.e. incomplete), or False if the latest year must be complete (the default behaviour). Setting this to True is mainly useful if you are fetching time-series data (via TimeSeriesDataSpec) and you want it to include the current (incomplete) year, including values for the current (incomplete) day. See allowPartialLatest for more on this.

Raises:

TypeError – if period is not a Period object, or if startOfYear is not a degreedays.time.StartOfYear object, or if allowPartialLatest is not a bool.

property allowPartialLatest: bool¶

True if the latest day range can be partially filled (i.e. incomplete); False otherwise (the default case).

When specifying time-series data (like hourly temperature data) via a TimeSeriesDataSpec, you can specify a breakdown with this allowPartialLatest property set to True, to tell the API to include values for the current day so far. For example:

hourlyTempsIncludingToday = DataSpec.timeSeries(
    TimeSeriesCalculation.hourlyTemperature(TemperatureUnit.CELSIUS),
    DatedBreakdown.daily(Period.latestValues(31), allowPartialLatest=True))

If you requested the above-specified hourly temperature data at, say, 11:42 on any given day, you could expect it to include values for 00:00, 01:00, 02:00 through to 11:00 on that day (bearing in mind that some stations are slower to report than others so you won’t always get the absolute latest figures).

Please note that the most recent time-series data can be a little volatile, as weather stations sometimes send multiple reports for the same time, some delayed, and some marked as corrections for reports they sent earlier. Our system generates time-series data using all the relevant reports that each weather station has sent, but the generated figures may change if delayed or corrected reports come through later. If you are storing partial-latest time-series data we suggest you overwrite it later with figures generated after the day has completed and any delayed/corrected reports have had time to filter through.

This allowPartialLatest property exists mainly for time-series data, but you can also set it to True on a breakdown for degree days, to specify that the data can include a value for the latest partial week/month/year. For example:

monthlyHddIncludingPartialLatest = DataSpec.dated(
    Calculation.heatingDegreeDays(Temperature.fahrenheit(65)),
    DatedBreakdown.monthly(Period.latestValues(12), allowPartialLatest=True))

If you requested the above-specified monthly degree-day data on, say, June 22nd, you could expect the last of the 12 values returned to cover from the start of June 1st through to the end of June 21st (assuming a good weather station with frequent reporting and minimal delays). If you left allowPartialLatest with its default value of False, the last of the 12 values returned would be for the full month of May (i.e. from the start of May 1st to the end of May 31st), as the monthly figure for June wouldn’t become available until June ended.

Unlike for time-series data (specified with TimeSeriesDataSpec), this property will never cause degree days to be calculated for partial days. So for degree days this property will only make a difference on weekly, monthly, yearly, and custom breakdowns with day ranges covering multiple days.

Any partial-latest day range will always start on the usual day (i.e. it will never be cut short at the start), it’s only the end that can be cut short. This is true for both degree days and time-series data.

property period: Period¶: The period in time that the yearly breakdown should cover.

property startOfYear: StartOfYear¶: The degreedays.time.StartOfYear object indicating which day should be taken as the first of each year (inclusive).

`degreedays.api.data.impl`¶

Class summaries¶