|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
DegreeDaysApi (in DegreeDaysApi.dll) Version: 220.127.116.11 (18.104.22.168)
public LocationDataResponse GetLocationData(
Public Function GetLocationData (
request As LocationDataRequest
) As LocationDataResponse
- Type: DegreeDays.Api.DataLocationDataRequest
Specifies the data you want and the location you want it
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).
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
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
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
number of values or the
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.