.NET Client Library for Degree Days.net API

The .NET client library is now working well, and documented well. It's currently on version 0.9.x because we haven't yet ruled out the possibility of making some small breaking changes before the release of version 1.0. Any such breaking changes would almost certainly be very small, so don't let that stop you from developing against this library today.

• The client library: DegreeDaysApi.dll (version 0.9.3). For changes since earlier versions, see the release history.
• MSDN-style documentation is at http://dotnet.degreedays.net/

Quick-start guide

You'll need:

• .NET 2.0 or later.
• The client-library DLL above. It has zero dependencies so no other DLLs are required.
• Your API access keys (account key and security key).

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);
}

Just swap in your 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...

• The LocationDataRequest is highly configurable:
  • You can specify the Location you want data for as a weather-station ID or a geographic location (postal/zip code, or longitude/latitude position). For geographic locations the API will automatically select the best weather station to satisfy your request.
  • There are various components to enable you to specify exactly what each set of data should contain. You can specify a daily, weekly, monthly, yearly, or average Breakdown, and there are several ways to specify the Period of coverage that you want.
  • You can fetch multiple sets of data from a location in a single request. For example, you might want to fetch HDD and CDD with multiple base temperatures each.
• The LocationDataResponse also contains information about the weather station(s) used to generate the returned data. If you request data from a geographic location initially, you might want to use the station ID to fetch updates later.
• Error handling would be important for production code. More on this below:

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:

• station IDs - see Location.StationId(String);
• postal codes - see Location.PostalCode(String, String); and
• (if you're making a distributable application) API access keys - see the constructors for AccountKey and SecurityKey.

All the methods/constructors listed above will throw an 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 method is DataApi.GetLocationData(LocationDataRequest). Follow that link 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:

• For a user-driven web application, you might want to catch LocationException explicitly so that you can tell if a user entered an unrecognized or unsupported station ID or postal/zip code. But anything else might just be DegreeDaysApiException as far as you are concerned - the request for data failed, and that might be all that matters.
• For a distributable application into which the user enters their own API access keys, you might want to catch InvalidRequestException explicitly so that you can prompt the user to check their API access keys for typos.
• For a long-running application that builds and maintains a database of degree-day data, you'll probably want to consider the various exceptions more carefully to determine which failed requests deserve a retry (perhaps after a wait), and to make sure that one request failure can't kill your long-running process completely.

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, because of data reporting delays, usually not for at least a few hours after that.)

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:

• The only properties or methods that will ever return null / Nothing return a Nullable type.
• There are very few methods or constructors that will accept null / Nothing as an argument. Passing a null / Nothing argument where it is not allowed will immediately result in an exception (fail fast).
• The API will never return degree-day data with gaps in it. No gaps, and no special error values like NaN, 0, -1, 9999 etc.
• The client library is built to work well in a multi-threaded environment.

Choose your Plan and Sign Up Today!