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; false otherwise.
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; false otherwise.

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; false otherwise.

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; false otherwise.

This can happen if you request data for a weather station that is "inactive", as explained further below.

In theory this can also happen if you request data for a GeographicLocation for which the API is unable to find an active weather station, but in practice this shouldn't occur because the global grid stations in our system can provide data for every location on Earth.

Inactive stations

An inactive station is one that has not sent any usable weather reports for roughly 10 days or more (10 being an approximate number that is subject to change).

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

See Also:

Failure codes, isDueToXXX() methods