Click or drag to resize

DataApi Class

Provides easy, type-safe access to the API's data-related operations.
Inheritance Hierarchy
SystemObject
  DegreeDays.Api.DataDataApi

Namespace:  DegreeDays.Api.Data
Assembly:  DegreeDays (in DegreeDays.dll) Version: 1.3
Syntax
public sealed class DataApi

The DataApi type exposes the following members.

Constructors
  NameDescription
Public methodDataApi(IRequestProcessor)
Constructs a DataApi object that uses the specified IRequestProcessor internally.
Top
Methods
  NameDescription
Public methodGetLocationData(LocationDataRequest)
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.
Public methodGetLocationInfo(LocationInfoRequest)
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.
Top
Remarks

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 IRequestProcessor passed into its constructor, so, if you have an IRequestProcessor, 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);
foreach (DatedDataValue v in hddData.Values) {
    Console.WriteLine(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", and you can read more about it in the remarks for the GeographicLocation class.
  • 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 DataSpecs to see exactly what subclasses of DegreeDaysApiException can be thrown.
Thread Safety
This class is designed to be safe for use from multiple concurrent threads. However, if you create a customized instance of this class (using an IRequestProcessor that you have written or customized), then the thread-safety of its operation will depend on the thread-safety of that IRequestProcessor.
See Also