Class: NWS::Point

Inherits:
Object
  • Object
show all
Defined in:
lib/nws/point.rb

Overview

Represents a geographic point and provides access to weather data for that location

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(data, client:) ⇒ Point

Initialize a Point from API response data

Parameters:

  • data (Hash) —

    Parsed JSON response from the points API

  • client (Client) —

    NWS API client instance



49
50
51
52
53
 
# File 'lib/nws/point.rb', line 49

def initialize(data, client:)
  @client = client
  @raw_data = data
  parse_data(data)
end

Instance Attribute Details

#city ⇒ String (readonly)

Returns City name for the point.

Returns:

  • (String) —

    City name for the point



34
35
36
 
# File 'lib/nws/point.rb', line 34

def city
  @city
end

#forecast_grid_data_url ⇒ String (readonly)

Returns URL for the forecast grid data endpoint.

Returns:

  • (String) —

    URL for the forecast grid data endpoint



28
29
30
 
# File 'lib/nws/point.rb', line 28

def forecast_grid_data_url
  @forecast_grid_data_url
end

#forecast_hourly_url ⇒ String (readonly)

Returns URL for the hourly forecast endpoint.

Returns:

  • (String) —

    URL for the hourly forecast endpoint



25
26
27
 
# File 'lib/nws/point.rb', line 25

def forecast_hourly_url
  @forecast_hourly_url
end

#forecast_url ⇒ String (readonly)

Returns URL for the forecast endpoint.

Returns:

  • (String) —

    URL for the forecast endpoint



22
23
24
 
# File 'lib/nws/point.rb', line 22

def forecast_url
  @forecast_url
end

#grid_id ⇒ String (readonly)

Returns NWS grid identifier (e.g., “LWX”).

Returns:

  • (String) —

    NWS grid identifier (e.g., “LWX”)



13
14
15
 
# File 'lib/nws/point.rb', line 13

def grid_id
  @grid_id
end

#grid_x ⇒ Integer (readonly)

Returns X coordinate on the NWS grid.

Returns:

  • (Integer) —

    X coordinate on the NWS grid



16
17
18
 
# File 'lib/nws/point.rb', line 16

def grid_x
  @grid_x
end

#grid_y ⇒ Integer (readonly)

Returns Y coordinate on the NWS grid.

Returns:

  • (Integer) —

    Y coordinate on the NWS grid



19
20
21
 
# File 'lib/nws/point.rb', line 19

def grid_y
  @grid_y
end

#latitude ⇒ Float (readonly)

Returns Latitude of the point.

Returns:

  • (Float) —

    Latitude of the point



7
8
9
 
# File 'lib/nws/point.rb', line 7

def latitude
  @latitude
end

#longitude ⇒ Float (readonly)

Returns Longitude of the point.

Returns:

  • (Float) —

    Longitude of the point



10
11
12
 
# File 'lib/nws/point.rb', line 10

def longitude
  @longitude
end

#observation_stations_url ⇒ String (readonly)

Returns URL for the observation stations endpoint.

Returns:

  • (String) —

    URL for the observation stations endpoint



31
32
33
 
# File 'lib/nws/point.rb', line 31

def observation_stations_url
  @observation_stations_url
end

#raw_data ⇒ Hash (readonly)

Returns Raw API response data.

Returns:

  • (Hash) —

    Raw API response data



43
44
45
 
# File 'lib/nws/point.rb', line 43

def raw_data
  @raw_data
end

#state ⇒ String (readonly)

Returns State abbreviation for the point.

Returns:

  • (String) —

    State abbreviation for the point



37
38
39
 
# File 'lib/nws/point.rb', line 37

def state
  @state
end

#time_zone ⇒ String (readonly)

Returns Time zone identifier (e.g., “America/New_York”).

Returns:

  • (String) —

    Time zone identifier (e.g., “America/New_York”)



40
41
42
 
# File 'lib/nws/point.rb', line 40

def time_zone
  @time_zone
end

Class Method Details

.fetch(lat, lon, client: NWS.client) ⇒ Point

Fetch point data for given coordinates

Parameters:

  • lat (Float) —

    Latitude

  • lon (Float) —

    Longitude

  • client (Client) (defaults to: NWS.client) —

    NWS API client instance

Returns:

  • (Point) —

    Point instance with location data

Raises:



62
63
64
65
66
67
68
69
 
# File 'lib/nws/point.rb', line 62

def self.fetch(lat, lon, client: NWS.client)
  validate_coordinates(lat, lon)
  lat_rounded = lat.round(4)
  lon_rounded = lon.round(4)

  data = client.get("/points/#{lat_rounded},#{lon_rounded}")
  new(data, client: client)
end

.validate_coordinates(lat, lon) ⇒ Object

Validate that coordinates are valid and within US coverage area

Parameters:

  • lat (Float) —

    Latitude

  • lon (Float) —

    Longitude

Raises:



127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/nws/point.rb', line 127

def self.validate_coordinates(lat, lon)
  lat = lat.to_f
  lon = lon.to_f

  unless lat.between?(-90, 90)
    raise InvalidCoordinatesError, "Latitude must be between -90 and 90"
  end

  unless lon.between?(-180, 180)
    raise InvalidCoordinatesError, "Longitude must be between -180 and 180"
  end

  # NWS API only covers US territories
  unless lat.between?(18, 72) && lon.between?(-180, -65)
    raise InvalidCoordinatesError, "Coordinates must be within US coverage area"
  end
end

Instance Method Details

#current_conditions ⇒ Observation

Get current weather conditions for this point

Returns:

Raises:



107
108
109
110
111
 
# File 'lib/nws/point.rb', line 107

def current_conditions
  station = nearest_station
  raise NotFoundError.new("No observation stations found for this location") unless station
  station.latest_observation
end

#forecast ⇒ Forecast

Get the 7-day forecast for this point

Returns:

  • (Forecast) —

    Forecast data for this location



74
75
76
77
 
# File 'lib/nws/point.rb', line 74

def forecast
  data = @client.get_url(@forecast_url)
  Forecast.new(data, point: self)
end

#hourly_forecast ⇒ HourlyForecast

Get the hourly forecast for this point

Returns:



82
83
84
85
 
# File 'lib/nws/point.rb', line 82

def hourly_forecast
  data = @client.get_url(@forecast_hourly_url)
  HourlyForecast.new(data, point: self)
end

#location_string ⇒ String

Get a human-readable location string

Returns:

  • (String) —

    Location in “City, State” format



116
117
118
 
# File 'lib/nws/point.rb', line 116

def location_string
  [city, state].compact.join(", ")
end

#nearest_station ⇒ Station?

Get the nearest observation station to this point

Returns:

  • (Station, nil) —

    Nearest station or nil if none found



99
100
101
 
# File 'lib/nws/point.rb', line 99

def nearest_station
  observation_stations.first
end

#observation_stations ⇒ Array<Station>

Get observation stations near this point

Returns:

  • (Array<Station>) —

    Array of nearby weather stations, ordered by proximity



90
91
92
93
94
 
# File 'lib/nws/point.rb', line 90

def observation_stations
  data = @client.get_url(@observation_stations_url)
  features = data["features"] || []
  features.map { |f| Station.new(f, client: @client) }
end