Degree Days

Degree Days

Weather Data for Energy Saving

.NET Client Library for Degree Days.net API

The .NET client library is stable, well tested, and well documented. It is the recommended way to access the API from C#, Visual Basic .NET, and other .NET languages.

The client library is in NuGet here, and you can find it in Visual Studio by searching for "DegreeDays" in the NuGet Package Manager.

MSDN-style documentation is at https://dotnet.degreedays.net/ and IntelliSense docs are bundled together with the NuGet package – you should get them automatically when you install via the NuGet Package Manager.

NuGet installation is the best option for most projects, but you can also download the client library directly: DegreeDaysApi.dll; and the XML docs for IntelliSense: DegreeDaysApi.xml.

The .NET client library is currently at version 1.4. For changes since earlier versions, please see the release history.

.NET quick-start guide

You'll need:

Here's a simple example showing how to fetch the latest 12 months of 65F-base-temperature heating degree days from an automatically-selected weather station near Times Square, New York (US zip code 10036). The HDD figures are output to the command line:

DegreeDaysApi api = new DegreeDaysApi(
    new AccountKey(yourStringAccountKey),
    new SecurityKey(yourStringSecurityKey));

DatedDataSpec hddSpec = DataSpec.Dated(
    Calculation.HeatingDegreeDays(Temperature.Fahrenheit(65)),
    DatedBreakdown.Monthly(Period.LatestValues(12)));

LocationDataRequest request = new LocationDataRequest(
    Location.PostalCode("10036", "US"),
    new DataSpecs(hddSpec));

LocationDataResponse response = api.DataApi.GetLocationData(request);

DatedDataSet hddData = response.DataSets.GetDated(hddSpec);

foreach (DatedDataValue v in hddData.Values) {
    Console.Out.WriteLine(v.FirstDay + ": " + v.Value);
}
Dim api As New DegreeDaysApi( _
    New AccountKey(yourStringAccountKey), _
    New SecurityKey(yourStringSecurityKey))

Dim hddSpec As DatedDataSpec = DataSpec.Dated( _
    Calculation.HeatingDegreeDays(Temperature.Fahrenheit(65)), _
    DatedBreakdown.Monthly(Period.LatestValues(12)))

Dim request As New LocationDataRequest( _
    Location.PostalCode("10036", "US"), _
    New DataSpecs(hddSpec))

Dim response As LocationDataResponse = api.DataApi.GetLocationData(request)

Dim hddData As DatedDataSet = response.DataSets.GetDated(hddSpec)

For Each v As DatedDataValue In hddData.Values
    Console.Out.WriteLine(v.FirstDay.ToString() & ": " & v.Value)
Next

Just swap in your API access keys (account key and security key) and the example code above should work right away.

But bear in mind that this example is just a starting point...

Error handling

Local input validation

The .NET client library tries its best to fail fast on invalid input. We'd rather give you an exception immediately than use up your rate limit with invalid API requests that are destined to fail.

This is mainly relevant if you are dealing with user input, particularly for:

All the methods/constructors listed above will throw a FormatException (or subclass) if they are passed an ID, code, or key that is clearly invalid. If you are dealing with user input, you might want to catch those exceptions explicitly as a means of validation.

Failures in remote calls (DegreeDaysApiException)

All the exceptions that can arise from a remote call to the API servers extend from DegreeDaysApiException.

The methods that make a remote call to the API servers are accessible through DegreeDaysApi. At present the only such methods are DataApi.GetLocationData(LocationDataRequest), DataApi.GetLocationInfo(LocationInfoRequest), and RegressionApi.RunRegressions(RegressionRequest). Follow any of those links to see which subclasses of DegreeDaysApiException can be thrown.

There is also SourceDataException, which is thrown by the GetXXX methods on the DataSets objects that come back in response to requests for degree-day data. SourceDataException is also a subclass of DegreeDaysApiException.

Which, if any, of these exceptions you'll want to handle explicitly will depend on the nature of your application:

Getting less data than you requested

This isn't an error as such, but it's important to realize that, in certain circumstances, the API can return less data than you requested. For example, you might request 10 years of data for a certain weather station, but get only 5 years back if that's all the usable temperature data that the weather station has. Or you might request data up to and including yesterday, but get only data to the day before yesterday. (Note that you should never be able to get the data for yesterday until that day has finished in the location's local time zone, and it's best not to expect it until at least a couple of hours after that. More on update schedules here.)

There are clear rules about how and when the API can deliver less data than requested, and you can control this behaviour as well. See the documentation for DataApi.GetLocationData(LocationDataRequest) to find out more.

But otherwise there should be no surprises...

We've built the API and the .NET client library for robustness and predictability:

Higher-level integration help

This page focuses on the technical details, but is also worth reading the higher-level integration guide for tips on the various approaches to integrating with the API. We have helped a lot of businesses integrate their software with our API so we are very familiar with the patterns that work well for common use cases.

Choose your API Plan and Start Today!

© 2008–2024 BizEE Software – About | Contact | Privacy | Free Website | API | Integration Guide | API FAQ | API Sign-Up