DataApi Class

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);
}

Dim api As New DegreeDaysApi(
    New AccountKey(yourStringAccountKey),
    New SecurityKey(yourStringSecurityKey))
Dim hddSpec As DatedDataSpec = DataSpec.Dated(
    Calculation.HeatingDegreeDays(Temperature.Fahrenheit(65)),
    DatedBreakdown.Monthly(Period.LatestValues(12)))
Dim request As New LocationDataRequest(
    Location.PostalCode("10036", "US"),
    New DataSpecs(hddSpec))
Dim response As LocationDataResponse = api.DataApi.GetLocationData(request)
Dim hddData As DatedDataSet = response.DataSets.GetDated(hddSpec)
For Each v As DatedDataValue In hddData.Values
    Console.WriteLine(v.FirstDay.ToString() & ": " & v.Value)
Next

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.

Reference