net.degreedays.api.data
Class DataApi

java.lang.Object
  extended by 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...

See Also:
getLocationData(LocationDataRequest)

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
DataApi(RequestProcessor requestProcessor)
          Constructs a DataApi object that uses the specified RequestProcessor internally.
 
Method Summary
 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:

When you request more data than is available:

Other data guarantees:

Parameters:
request - specifies the data you want and the location you want it for.
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 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).
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 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.


www.degreedays.net/api/