Java Client Library for Degree Days.net API

The Java client library is stable, well tested, and well documented. It is the recommended way to access the API from Java or other JVM languages like Kotlin, Scala, Groovy etc.

The client library and javadoc jars are in Maven Central, you can get the code for Maven/Gradle/Ivy etc. here. Alternatively you can download the client library directly: DegreeDaysApi-1.4.jar.

Javadocs are online at https://javadoc.degreedays.net/ or you can get them through Maven (see above) or download a zip file for offline use.

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

Java quick-start guide

You'll need:

• Java 1.5 or later. (We love backwards compatibility!)
• The client-library jar file described above (either through Maven or by downloading it directly). It has zero dependencies so no other jar files are required.
• Your API access keys (account key and security key). You'll get these immediately after you sign up for an API account.

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 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...

• 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.
  • A DataSpec can be a DatedDataSpec (for daily/weekly/monthly/yearly HDD/CDD), an AverageDataSpec (for average degree days like 10-year-average HDD), or a TimeSeriesDataSpec (for time-series data like hourly temperature data). Follow the links to see sample code for each.
  • There are various other options to enable you to specify exactly what each set of data should contain. For example, with a DatedBreakdown you can specify daily, weekly, monthly, or yearly data, and there are several ways to specify the Period that you want it to cover.
  • You can fetch multiple sets of data from a location in a single request. The sample code above creates a DataSpecs with just one DataSpec, but you can have up to 120 DataSpec objects in a single request (to get up to 120 sets of data back in the response). For example, you might want to fetch HDD and CDD with multiple base temperatures each, and hourly temperature data, all in one request.
• 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. If you are specifying geographic locations, but storing data by station ID, you can avoid re-fetching data unnecessarily by using DataApi.getLocationInfo(LocationInfoRequest) to get the station ID that would be returned by an equivalent call to DataApi.getLocationData(LocationDataRequest). We call this two-stage data fetching (also discussed here in the integration guide).
• There's RegressionRequest too. With it you can send energy data to the API so it can test thousands of regressions and find the HDD and/or CDD base temperatures that give the best statistical fit. We cover this fully in our docs on the API's regression functionality.
• Error handling would be important for production code. More on this below:

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:

• 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 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), 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:

• 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 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:

• The only methods in net.degreedays classes that will ever return null have "OrNull" in their names. For example: DayRange.intersectionOrNull(DayRange).
• There are very few methods or constructors that will accept null as an argument. Passing a null 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.

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!