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 65°F-base-temperature heating degree days for an automatically-selected weather station near US zip code 02633 (which is on Cape Cod so you can use the free test API account). The HDD figures are output to the command line:

// The free test account will work for locations on Cape Cod.  Swap in your own
// API access keys to fetch data for locations worldwide.
DegreeDaysApi api = new DegreeDaysApi(
        new AccountKey("test-test-test"),
        new SecurityKey("test-test-test-test-test-test-test-test-test-test-test-test-test"));

DatedDataSpec hddSpec = DataSpec.dated(
        Calculation.heatingDegreeDays(Temperature.fahrenheit(65)),
        DatedBreakdown.monthly(Period.latestValues(12)));

// Tip: add more DataSpec items to fetch e.g. CDD or hourly temperatures in the
// same request. The API docs for getLocationData have sample code showing how:
// https://javadoc.degreedays.net/#net/degreedays/api/data/DataApi#multiple-sets

LocationDataRequest request = new LocationDataRequest(
        Location.postalCode("02633", "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());
}

Bear in mind that this example is just a starting point...

The LocationDataRequest is highly configurable:

There are multiple ways to specify the various components of the LocationDataRequest:

// The Location can be a station ID, or a "geographic location" for which the
// API will select the best weather station to use automatically:
Location.stationId("KHYA");
Location.longLat(new LongLat(-70.30563, 41.69547));
Location.postalCode("02633", "US");

// Calculation:
Calculation.heatingDegreeDays(Temperature.fahrenheit(65));
Calculation.coolingDegreeDays(Temperature.celsius(21.5));

// A TimeSeriesCalculation is for time-series data like hourly temperature data:
TimeSeriesCalculation.hourlyTemperature(TemperatureUnit.CELSIUS);

// Period of coverage:
Period.latestValues(12);
Period.dayRange(new DayRange(Day.of(2024, 1, 1), Day.of(2024, 12, 31)));
// By default you may get back less data than you requested if there aren't
// enough records to generate a full set for your specified location.  But you
// can specify a minimum if you would rather have a failure than too little
// data.  For example, if you want 60 values but will accept 36+:
Period.latestValues(60).withMinimumNumberOfValues(36);
// Or if you want 10 specific years, and would rather a failure than anything less:
Period.dayRange(new DayRange(Day.of(2015, 1, 1), Day.of(2024, 12, 31)))
    .withMinimumDayRange(new DayRange(Day.of(2015, 1, 1), Day.of(2024, 12, 31)));

// DatedBreakdown (using a period like those specified above):
DatedBreakdown.daily(period);
DatedBreakdown.weekly(period, DayOfWeek.MONDAY); // specifying firstDayOfWeek
DatedBreakdown.monthly(period);
DatedBreakdown.monthly(period, StartOfMonth.of(5));
DatedBreakdown.yearly(period);
DatedBreakdown.yearly(period, StartOfYear.of(6, 22));
DatedBreakdown.custom(DayRanges.of(
    new DayRange(Day.of(2024, 12, 15), Day.of(2025, 1, 12)),
    new DayRange(Day.of(2025, 1, 13), Day.of(2025, 2, 17)),
    new DayRange(Day.of(2025, 2, 24), Day.of(2025, 3, 18))));
// All the DatedBreakdown types let you specify .withAllowPartialLatest(true)
// so you can fetch time-series data that includes the current day so far.  For
// example:
DatedBreakdown.daily(period).withAllowPartialLatest(true);

// AverageBreakdown has just one type at present, which specifies an average of
// the data for the full calendar years specified by the period:
AverageBreakdown.fullYears(period);

// A DataSpec is a specification for a set of data, made up of
// Calculation/Period/Breakdown objects like those specified above:
DataSpec.dated(calculation, datedBreakdown); // for HDD or CDD
DataSpec.average(calculation, averageBreakdown); // for average HDD or CDD
DataSpec.timeSeries(timeSeriesCalculation, datedBreakdown); // for e.g. hourly temperature data

// Putting all this together, here are a few example DataSpec items:
DatedDataSpec hddSpec = DataSpec.dated(
    Calculation.heatingDegreeDays(Temperature.fahrenheit(60)),
    DatedBreakdown.monthly(Period.latestValues(12)));
DatedDataSpec cddSpec = DataSpec.dated(
    Calculation.coolingDegreeDays(Temperature.celsius(21)),
    DatedBreakdown.daily(Period.dayRange(
        new DayRange(Day.of(2024, 1, 1), Day.of(2024, 12, 31)))));
AverageDataSpec averageHddSpec = DataSpec.average(
    Calculation.heatingDegreeDays(Temperature.celsius(15.5)),
    AverageBreakdown.fullYears(Period.latestValues(5)));
TimeSeriesDataSpec hourlyTemperaturesSpec = DataSpec.timeSeries(
    TimeSeriesCalculation.hourlyTemperature(TemperatureUnit.FAHRENHEIT),
    DatedBreakdown.daily(Period.latestValues(30)));
TimeSeriesDataSpec hourlyTemperaturesIncludingTodaySpec = DataSpec.timeSeries(
    TimeSeriesCalculation.hourlyTemperature(TemperatureUnit.CELSIUS),
    DatedBreakdown.daily(Period.latestValues(31)).withAllowPartialLatest(true));

// DataSpec objects go into a DataSpecs object:
new DataSpecs(hddSpec); // HDD only (with only one base temperature and breakdown)
new DataSpecs(hddSpec, cddSpec); // HDD and CDD
new DataSpecs(hddSpec, cddSpec, hourlyTemperaturesSpec); // HDD, CDD, and hourly temperature data
new DataSpecs(listOfUpTo120DataSpecObjects); // e.g. HDD & CDD with a range of base temperatures or breakdowns

Note above how you can specify multiple sets of data (e.g. HDD, CDD, hourly temperature data) to be fetched in a single request. This is faster and uses fewer request units than making multiple requests for the same location. The second code sample in the docs for getLocationData shows how.

The LocationDataResponse contains more than just data:

It also contains information about the weather station(s) used to generate the returned data. For example, if you request data for a geographic location initially, you might want to use the station ID to fetch updates later:

System.out.println(response.stationId());

LocationInfoRequest and two-stage data fetching:

Except in name, LocationInfoRequest looks exactly the same as LocationDataRequest. Using it is almost identical too:

// Assuming location, dataSpecs, and api are already defined (see examples above)
LocationInfoResponse locationInfoResponse = 
    api.dataApi().getLocationInfo(new LocationInfoRequest(location, dataSpecs));
System.out.println(locationInfoResponse.stationId());

But LocationInfoResponse does not contain any data (it has no DataSets)... It's typically used for two-stage data fetching, which can be useful if you are dealing with geographic locations (postal/zip codes, or longitude/latitude positions), but storing data by station ID (returned in every successful response). For this use-case, two-stage data fetching can help you save request units (see right) and improve the efficiency of your system by avoiding re-fetching data that you already have stored.

When you want to add a new location into your system (e.g. if a new user signs up with a new address), you can do the following:

• Stage 1: Make a LocationInfoRequest with the geographic location and the specification of the data that you want. This will only take one request unit. You won't get any data back, but you should get the station ID that the system would use for an equivalent LocationDataRequest. If you already have data stored for that station ID, use it and skip Stage 2; if not, proceed to Stage 2.
• Stage 2 (only if needed): Make a LocationDataRequest with the station ID from Stage 1. Using the station ID here (as opposed to the geographic location) saves you a request unit, thus offsetting the request unit used in Stage 1. But fetching data can still use a lot of request units – more the more data you fetch – so the efficiency of two-stage data fetching comes from skipping this Stage 2 fetch whenever possible.

If none of your geographic locations share a weather station, two-stage data fetching will use exactly the same number of request units as simply fetching data for each geographic location. But two-stage data fetching will improve efficiency and save request units if/when you have enough geographic locations in your system that some of them end up sharing weather stations. If that is the case, two-stage data fetching can really help your system to scale well as more and more geographic locations are added in.

There's also RegressionRequest for advanced regression functionality:

With RegressionRequest 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

Error handling would be important for production code:

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). For example:

DegreeDaysApi api = new DegreeDaysApi(
        new AccountKey(yourStringAccountKey),
        new SecurityKey(yourStringSecurityKey));
LocationDataResponse response =
        api.dataApi().getLocationData(yourLocationDataRequest);

getLocationData, getLocationInfo, and runRegressions can throw a range of subclasses of DegreeDaysApiException:

• LocationException – if the request fails because of problems relating to the specified Location;
• ServiceException – if the request fails because of a problem with the API service (sorry!);
• RateLimitException – if you hit the rate limit for your account's plan, and need to wait a little while before it's reset (you can check .metadata().rateLimit().minutesToReset() on any successful response, or .responseMetadata().rateLimit().minutesToReset() on any RateLimitException to see how long it will be until the next reset);
• InvalidRequestException – if the request that is sent to the API servers is invalid (e.g. if it is authenticated with invalid access keys);
• TransportException – if there's a problem sending the request to the API servers, or a problem getting the API's response back;
• DegreeDaysApiException – the superclass of all the exceptions listed above.

There is also SourceDataException (another subclass of DegreeDaysApiException), which can be thrown by the getXXX methods on the DataSets objects that come back in response to requests for data. For example:

try {
    DatedDataSet hddSet = response.dataSets().getDated(hddSpec);
} catch (SourceDataException e) {
    // hddSpec couldn't be fulfilled as there wasn't enough good temperature
    // data to calculate degree days covering the specified period.
}

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 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 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 data with gaps in it (unless you explicitly specify a custom breakdown or regression input data with gaps). No unexpected 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.

Further reading

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

There are separate docs covering the API's regression functionality.

The detailed Javadoc explain every class and method in the Java client library, along with detailed notes about the different request options, the types of response data, and the exceptions. It's the place to go for lower-level details on using the API from Java.

Choose your API Plan and Start Today!