net.degreedays.api.data
Class Station

java.lang.Object
  extended by net.degreedays.api.data.Station
All Implemented Interfaces:
java.io.Serializable

public final class Station
extends java.lang.Object
implements java.io.Serializable

Contains basic information about a weather station.

Instances of this class are immutable. You can safely reuse them and call them from multiple threads at once.


Nested Class Summary
static class Station.Builder
          A builder class for creating immutable Station objects e.g. for testing purposes.
 
Method Summary
 java.lang.String displayName()
          Returns a non-null, non-empty string representing the name of the weather station.
 Distance elevation()
          Returns the non-null elevation of the weather station.
 boolean equals(java.lang.Object o)
          Returns true if o is a Station object with equal fields to this.
 int hashCode()
          Overridden to ensure consistency with equals.
 java.lang.String id()
          Returns the non-null, non-empty, canonical ID of the weather station.
 LongLat longLat()
          Returns the non-null longitude/latitude location of the weather station.
 java.lang.String toString()
          Returns a non-null, non-empty string representation of this object for logging and debugging purposes.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Method Detail

id

public java.lang.String id()
Returns the non-null, non-empty, canonical ID of the weather station. (See LocationDataResponse.stationId() for an explanation of what "canonical" means in this context.)

The ID can be used to request data from this station.


displayName

public java.lang.String displayName()
Returns a non-null, non-empty string representing the name of the weather station.

The returned name should not include the ID, the longitude/latitude, or the elevation. So, for displaying the name of a station in a UI, at a minimum you'll probably want to do something like:

 station.id() + ": " + station.displayName()
 

You might also want to display the longitude/latitude and elevation too.

We'd love to be able to break the details within this name down further (e.g. offering separate fields for city, state, and country)... But the recorded details for weather stations names are generally too unreliable for this to make sense. Fields are often misspelled, mixed up (e.g. the state might have been entered into the city field), and required fields like country are often missing. And there's little consistency in the naming (e.g. United Kingdom, Great Britain, GB, UK etc.). This, unfortunately, is a limitation of the original data sources - it's typical for the IDs to be monitored and controlled closely, but it's rare for the names to receive the same level of attention.

Please be aware that a weather stations's display name may change over time, both in content and format. We strongly suggest that you don't try to parse these names. But please do let us know if there's something in particular that you need access to.


longLat

public LongLat longLat()
Returns the non-null longitude/latitude location of the weather station.

Note that a weather station's recorded location might not be a particularly accurate representation of its real-world location. Many stations do have recorded longitude/latitude locations that are accurate to within a few metres, but there are many that out by as much as a kilometer or so. This is worth bearing in mind when you're calculating the distances between locations.

Note also that the recorded location of weather stations will often change over time as the underlying data sources are updated with more accurate measurements.


elevation

public Distance elevation()
Returns the non-null elevation of the weather station. The Distance object returned can easily be converted into units of your choice (typically metres or feet for an elevation).

Note that the reliability of these measurements is variable. Note also that they may change over time as the underlying data sources are updated with more accurate measurements.


equals

public boolean equals(java.lang.Object o)
Returns true if o is a Station object with equal fields to this. Note that, under certain circumstances, you might just want to compare station IDs for equality (like station1.id().equals(station2.id())). It's possible for fields like the display name to change over time, but the ID of a station should remain constant.

Overrides:
equals in class java.lang.Object

hashCode

public int hashCode()
Overridden to ensure consistency with equals.

Overrides:
hashCode in class java.lang.Object

toString

public java.lang.String toString()
Returns a non-null, non-empty string representation of this object for logging and debugging purposes.

The exact details of the representation are unspecified and subject to change.

Overrides:
toString in class java.lang.Object


www.degreedays.net/api/