GeographicLocation Class

To create a GeographicLocation object you can use Location's PostalCode(String, String) and LongLat(LongLat) static factory methods. For example:

GeographicLocation empireStateBuilding = 
    Location.PostalCode("10118", "US");

GeographicLocation trafalgarSquare = 
    Location.LongLat(new LongLat(-0.12795, 51.50766));

Dim empireStateBuilding As GeographicLocation = 
    Location.PostalCode("10118", "US")

Dim trafalgarSquare As GeographicLocation =
    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.

Fetching more data from the same location (e.g. daily updates)

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 organizations such as the NWS or 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.

Two-stage data fetching from geographic locations

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 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 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.

Reference