net.degreedays.api.data

Class LocationException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

net.degreedays.api.DegreeDaysApiException

net.degreedays.api.FailureException

net.degreedays.api.RequestFailureException

net.degreedays.api.data.LocationException

All Implemented Interfaces:

java.io.Serializable

public final class LocationException
extends RequestFailureException

Indicates a Failure in the API's processing of a request, caused by problems with the Location that the request specified.

This exception corresponds to any failure code starting with "Location".

You can interrogate the isDueToXXX() methods of this exception to find out more about the cause. But do note that it is possible for none of those methods to return true if a relevant new failure code is added into the API. Be prepared for this in your handling.

You might not need to pay any attention to the specific code behind the LocationException. For many use-cases, the best way to handle a LocationException is just to try again with an alternative location. For example, if a request for data from a specific station ID fails, you might want to try a request for the GeographicLocation of the real-world building you ultimately want data for, so that the API can find a replacement station for you automatically.

Method Summary

Modifier and Type	Method and Description
boolean	isDueToLocationNotRecognized() Returns true if this failure came in response to a request for data from a location that the API did not recognize as a weather station or real-world geographic location.
boolean	isDueToLocationNotSupported() Returns true if this failure came in response to a request for data from a location that is recognized but not currently supported by the API.

Methods inherited from class net.degreedays.api.RequestFailureException

responseMetadata

Methods inherited from class net.degreedays.api.FailureException

failure, getMessage

Methods inherited from class java.lang.Throwable

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

isDueToLocationNotRecognized

public boolean isDueToLocationNotRecognized()

Returns true if this failure came in response to a request for data from a location that the API did not recognize as a weather station or real-world geographic location.

This type of failure will occur if you specify a StationIdLocation with an unrecognized ID, or a PostalCodeLocation with an unrecognized postal code.

See Also:

Failure codes, isDueToXXX() methods

isDueToLocationNotSupported

public boolean isDueToLocationNotSupported()

Returns true if this failure came in response to a request for data from a location that is recognized but not currently supported by the API.

This can happen if you request data from a GeographicLocation for which the API is unable to find a good weather station. In this instance it is possible that a weather station with usable data does exist in the area - you could try visiting www.degreedays.net and searching manually to see if you can find a good weather station to use for future API requests (referencing it by station ID). But you will probably have to look some distance from the location of interest to find a usable station.

This can also happen if you request data from a weather station that has not sent any usable weather reports for roughly 10 days or more (10 being an approximate number that is subject to change). We call such stations "inactive".

Some stations have never reported valid temperatures, and so have always been inactive/not supported.

It's fairly rare for active stations to go inactive, but it does happen, and it's best to be prepared for the possibility, particularly if you're handling data from hundreds or thousands of locations. Stations can be taken down, they can break (and not be fixed in a timely manner), or they can be moved to another location and assigned a new ID. Unfortunately not even the best "airport" stations managed by organizations such as the NWS or UK Met Office are exempt from these sorts of problems.

Short periods of station inactivity should not result in this failure. Up to a point, the API will fill in missing data with estimates. It's only when a station fails to send any usable data for roughly 10 days or more that the API will consider it inactive. (10 being an approximate number that is subject to change.)

It's possible for an inactive station to become active (again) at some point in the future. However, if you get this failure for a station, you're probably best off finding another nearby station to use as an alternative/replacement (e.g. by requesting data using the GeographicLocation of the real-world building of interest). If an active station goes inactive, and then later makes a revival, there will probably be a gap in its data coverage that will make it impractical for use in most forms of degree-day-based analysis until it has accumulated more uninterrupted data.

See Also:

Failure codes, isDueToXXX() methods