Degree Days

Degree Days

Weather Data for Energy Professionals

Weather Underground

Java Client Library for Degree Days.net API

The Java client library is stable, well tested, and well documented.

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

for (DatedDataValue v : hddData.getValues()) {
    System.out.println(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...

Error handling

Local input validation

The Java client library tries its best to fail fast on invalid input. We'd rather give you an IllegalArgumentException 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 an IllegalArgumentException (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) and DataApi.getLocationInfo(LocationInfoRequest). Follow either 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:

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 Java 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 Plan and Sign Up Today!

© 2018 BizEE Software Limited - About | Contact | Privacy | Web Tool | API | Integration Guide | API FAQ | API Sign-Up