public abstract class GeographicLocation extends Location
Defines a location in terms of a longitude/latitude or postal/zip code, leaving it to the API to find the nearest good weather station.
To create a GeographicLocation object you can use
Location's postalCode and
longLat static factory methods. For example:
GeographicLocation empireStateBuilding = Location.postalCode("10118", "US");
GeographicLocation trafalgarSquare = Location.longLat(
new LongLat(-0.12795, 51.50766));
Geographic locations provide a powerful way to request degree-day data. Manually selecting the best weather station to provide data for a specific building or region can be tricky, because different stations have different levels of data coverage and quality. With a geographic location, the API will automatically select the weather station that is best-equipped to provide the data you want.
At some point the API might average data from multiple weather stations around the specified location if it thinks that would significantly improve results. If we do add this feature, it will be optional, and disabled by default, so the behaviour of your system won't change unless you want it to.
Make sure to specify the full range of data that you want when using a geographic location... Some weather stations have less data than others so it's important for the API to know the full range of interest when it's choosing which station(s) to use.
The LocationDataResponse contains a station ID that will enable you
to fetch more data from the weather station(s) that were selected for your
geographic location. If just one station was used (the normal case), then the
station ID will simply be the canonical ID of that one station. If data from
multiple stations was combined to satisfy your request (an option that isn't
available now but that we may cater for in future), then the station ID will
be for a "virtual station" that represents the specific combination of
weather stations used.
Either way, you can use the station ID from the
LocationDataResponse to fetch more data from the same location
in the future. For example, you might initially want to fetch the last 5
years of data from a geographic location, and then use the returned station
ID to fetch updates each day, week, or month going forward. If you're storing
the generated data, then doing it this way will ensure that your data updates
are generated using the same weather station(s) as your initial request.
However, if you're following this model, bear in mind that a weather station that works today won't necessarily be working next month or next year. It's not uncommon for weather stations to go out of service (including the "airport" stations that are managed by official sources like the NOAA and the UK Met Office). This possibility might not be worth worrying about if you're only tracking data from a handful of locations, but it's definitely worth planning for if you're tracking data from hundreds or thousands of locations. To prepare for a station going down, it makes sense to store the details of the geographic location together with the station ID that you're using for updates. That way, if the station fails, you can use the geographic location to find a replacement.
Note that a simple alternative is to use the geographic location to fetch a
full set of data each time it is needed. You might not get data from the same
station(s) each time (particularly if you vary the Period of coverage
that you request data for), but the station-selection algorithm will ensure
that you're getting the best available data for each individual request that
you make.
If you are using geographic locations, but storing data by station ID (as described above), you may be able to save request units and improve the efficiency of your system with two-stage data fetching. When you want to add a new location into your system (e.g. if a new user signs up with a new address), you can do the following:
Stage 1: Call DataApi.getLocationInfo(LocationInfoRequest)
with the geographic location and the specification of the data that you want.
You won't get any data back, but you should get the station ID that the
system would use for an equivalent LocationDataRequest. If you
already have data stored for that station ID, use it; if not, progress to
stage 2.
Stage 2: Call DataApi.getLocationData(LocationDataRequest)
with the station ID from stage 1. (You could use the geographic location
again, but using the station ID will save a request unit, such that your
two-stage fetch will take the same number of request units in total as it
would if you had just submitted a LocationDataRequest with the
geographic location in the first place.)
Two-stage fetching will only improve efficiency and save request units if/when you have enough geographic locations in your system that some of them end up sharing weather stations. But, if that is the case, two-stage fetching can really help your system to scale well as more and more geographic locations are added in.
This abstract class is not designed to be extended by third-party code, which is why it does not have an accessible constructor.
All concrete subclasses of this abstract class are immutable. You can safely reuse them and call them from multiple threads at once.
See www.degreedays.net/api/ for more about the Degree Days.net API.
You can sign up for a Degree Days.net API account and read the integration guide that is useful and applicable whether you are using Java or not.