net.degreedays.api.data

Class DataApi

java.lang.Object

net.degreedays.api.data.DataApi

public final class DataApi
extends java.lang.Object

Provides easy, type-safe access to the API's data-related operations.

Creating a DataApi object

Instead of creating a DataApi instance directly, you would typically create a DegreeDaysApi object and get the DataApi object from that. See here for more information and examples. Although the only state of a DataApi object is the RequestProcessor passed into its constructor, so, if you have a RequestProcessor, there's no reason not to create a DataApi object directly if doing it that way makes sense for your app.

Example code for fetching a simple set of degree-day data

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

• 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 that enable you to specify exactly what each set of data should contain. Each DataSpec can be either a DatedDataSpec (for daily, weekly, monthly, or yearly degree days), an AverageDataSpec (for average degree days), or a TimeSeriesDataSpec (for hourly temperature data). Each of these is configured with objects that determine the data Calculation (or TimeSeriesCalculation), the Breakdown, and 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. To do this just create the DataSpecs in your request with multiple different DataSpec items.
• 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 getLocationInfo(LocationInfoRequest) to get the station ID that would be returned by an equivalent call to getLocationData(LocationDataRequest). We call this two-stage data fetching.
• Error handling would be important for production code. Catching DegreeDaysApiException will cover everything that you should be prepared for, but it's often useful to get more detail. See getLocationData(LocationDataRequest) and the getXXX methods of DataSets to see exactly what subclasses of DegreeDaysApiException can be thrown.

See Also:

getLocationData(LocationDataRequest), getLocationInfo(LocationInfoRequest)

This class is designed to be safe for use from multiple concurrent threads. However, if you create a customized instance of this class (using a RequestProcessor that you have written or customized), then the thread-safety of its operation will depend on the thread-safety of that RequestProcessor.

Constructor Summary

Constructors

Constructor and Description
DataApi(RequestProcessor requestProcessor) Constructs a DataApi object that uses the specified RequestProcessor internally.

Method Summary

Modifier and Type	Method and Description
LocationDataResponse	getLocationData(LocationDataRequest request) Sends your request for data to the API servers, returning a non-null response containing data you requested, or throwing an appropriate subclass of DegreeDaysApiException if something goes wrong.
LocationInfoResponse	getLocationInfo(LocationInfoRequest request) A lightweight alternative to getLocationData(LocationDataRequest) that returns info about the station(s) that would be used to satisfy an equivalent LocationDataRequest, but not the data itself.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DataApi

public DataApi(RequestProcessor requestProcessor)

Constructs a DataApi object that uses the specified RequestProcessor internally.

Parameters:

requestProcessor - the non-null RequestProcessor that the new DataApi object should use internally for its processing.

Throws:

java.lang.NullPointerException - if requestProcessor is null.

Method Detail

getLocationData

public LocationDataResponse getLocationData(LocationDataRequest request)
                                     throws DegreeDaysApiException

Sends your request for data to the API servers, returning a non-null response containing data you requested, or throwing an appropriate subclass of DegreeDaysApiException if something goes wrong.

It's worth understanding the rules that govern what you can get in response to a request for one or more sets of data from a particular location:

Stations that data can come from:

• If your request specifies a StationIdLocation then the API will only ever return data from that station. It will never substitute in data from another station.
• If your request specifies a GeographicLocation, the API will choose which station(s) to use automatically. The choice will depend on the data you requested as well as the location you requested it for. Some stations have more data than others, and the quality of a station's data can vary over time. The API will choose the station(s) that can best satisfy your specific request.
• The API will never send a LocationDataResponse for an inactive station. An inactive station is one that hasn't sent any usable weather reports for roughly 10 days or more (10 being an approximate number that is subject to change). See here for more information on inactive stations. If you request data from an inactive station, or from a GeographicLocation for which no active station can be found, you will get a LocationException to indicate that the location is not supported.

When you request more data than is available:

• If your request specifies data from a location for which an active station exists, you should, barring other failures, get a LocationDataResponse. But, if any of the DataSpecs that you specified cannot be satisfied (either fully or partially), you will get a SourceDataException each time you try to get the corresponding DataSet from the DataSets object held by the response.
• If there's not enough data to fully satisfy your request, the API will return partial sets of data if it can. For example, you might request 10 years of data, but only get 5. Because data is only returned for active stations, you can rely on recent times being covered if requested (usually including yesterday's data in the station's time-zone, but always to within around 10 days or so of that day). But data from further back could be missing.
• If you'd rather the API gave you SourceDataExceptions (see above) than partially-complete data sets, make sure to specify the minimum number of values or the minimum day range on the Periods in your request. Unless you specify minimums, the API will return the best it can from within the specification you give.

Other data guarantees:

• Excepting the widening rules that apply when a DayRangePeriod is specified imprecisely, The API will never return more data than you asked for, or data from outside of the range that you asked for.
• The API will never return data with gaps in it. No gaps, and no special error values like NaN, 0, -1, 9999 etc. If a station has small gaps in its source temperature data, the API will fill those gaps with estimates before calculating any degree days. But larger gaps are not tolerated, and the API will only ever use data from after such gaps. If a larger gap is ongoing (i.e. there is no good data after it), the station will be declared inactive (see above). This approach ensures that active stations will always have contiguous sets of data that run through to recent days.

Parameters:

request - specifies the data you want and the location you want it for. Cannot be null.

Returns:

A non-null LocationDataResponse containing the data you requested or as much of it as was available for the location you specified (given the rules explained above).

Throws:

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 RateLimit for your account's plan, and need to wait a little while before it's reset.

InvalidRequestException - if the request that is sent to the API servers is invalid (e.g. if it is authenticated with invalid API 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.

java.lang.NullPointerException - if request is null.

getLocationInfo

public LocationInfoResponse getLocationInfo(LocationInfoRequest request)
                                     throws DegreeDaysApiException

A lightweight alternative to getLocationData(LocationDataRequest) that returns info about the station(s) that would be used to satisfy an equivalent LocationDataRequest, but not the data itself.

This can be useful if you have a database of data stored by station ID, but are using geographic locations (postal/zip codes or longitude/latitude positions) to determine which station ID to use for each of your real-world locations. A LocationInfoRequest only requires one request unit, whilst a large LocationDataRequest requires considerably more, so it often makes sense to use this to avoid the overhead of re-fetching data that you already have stored. We call this two-stage data fetching.

Note, however, that this returns nothing that isn't also returned by a call to getLocationData(LocationDataRequest). So, if you know you'll be fetching data anyway, you might as well use getLocationData(LocationDataRequest) from the start.

Exceptions and data availability:

The exceptions thrown by this method are the same as those thrown by getLocationData(LocationDataRequest), and they are thrown under exactly the same circumstances.

However, because this doesn't return any data (i.e. no DataSets), there's no way to tell from this whether an equivalent LocationDataResponse would actually contain any or all of the data you want. So, although you can use this to determine what station ID the API would use for an equivalent call to getLocationData(LocationDataRequest), you would have to actually make that call to be sure that you could get all the data you wanted.

Parameters:

request - specifies the location you want data for and the data that you want (as this can affect the station-selection process for geographic locations). Cannot be null.

Returns:

A non-null LocationInfoResponse containing info about the station(s) that would be used to satisfy an equivalent LocationDataRequest.

Throws:

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 RateLimit for your account's plan, and need to wait a little while before it's reset.

InvalidRequestException - if the request that is sent to the API servers is invalid (e.g. if it is authenticated with invalid API 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.

java.lang.NullPointerException - if request is null.

Since:

1.1