Click or drag to resize
DataApiGetLocationData Method
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.

Namespace: DegreeDays.Api.Data
Assembly: DegreeDaysApi (in DegreeDaysApi.dll) Version: 1.1.0.0 (1.1.0.0)
Syntax
public LocationDataResponse GetLocationData(
	LocationDataRequest request
)

Parameters

request
Type: DegreeDays.Api.DataLocationDataRequest
Specifies the data you want and the location you want it for.

Return Value

Type: LocationDataResponse
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 below).
Exceptions
ExceptionCondition
LocationExceptionThe request failed because of problems relating to the specified Location.
ServiceExceptionThe request failed because of a problem with the API service (sorry!).
RateLimitExceptionYou hit the RateLimit for your account's plan, and need to wait a little while before it's reset.
InvalidRequestExceptionThe request that is sent to the API servers is invalid (e.g. if it is authenticated with invalid API access keys).
TransportExceptionA problem sending the request to the API servers, or a problem getting the API's response back.
DegreeDaysApiExceptionThe superclass of all the exceptions listed above.
ArgumentNullExceptionrequest is null.
Remarks

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 data set 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 (see that class's documentation for more on widening), 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.
See Also