Class: FaaNotams::Service

Inherits:
Object
  • Object
show all
Defined in:
lib/faa_notams/service.rb

Overview

Service to interact with FAA’s Notice to Airmen (NOTAM) API external-api.faa.gov/notamapi

This service provides access to FAA’s NOTAM API, which contains real-time notification of any change in the National Airspace System (NAS).

Constant Summary collapse

BASE_URL = 
"https://external-api.faa.gov/notamapi/v1"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client_id = nil, client_secret = nil) ⇒ Service

Initialize the service with FAA API credentials

Parameters:

  • client_id (String) (defaults to: nil) —

    FAA API client ID

  • client_secret (String) (defaults to: nil) —

    FAA API client secret

Raises:

  • (ArgumentError) 


21
22
23
24
25
26
27
 
# File 'lib/faa_notams/service.rb', line 21

def initialize(client_id = nil, client_secret = nil)
  @client_id = client_id || ENV['FAA_NOTAM_CLIENT_ID']
  @client_secret = client_secret || ENV['FAA_NOTAM_CLIENT_SECRET']
  
  raise ArgumentError, "FAA NOTAM client_id is required" unless @client_id
  raise ArgumentError, "FAA NOTAM client_secret is required" unless @client_secret
end

Instance Attribute Details

#client_id ⇒ Object (readonly)

Returns the value of attribute client_id.



16
17
18
 
# File 'lib/faa_notams/service.rb', line 16

def client_id
  @client_id
end

#client_secret ⇒ Object (readonly)

Returns the value of attribute client_secret.



16
17
18
 
# File 'lib/faa_notams/service.rb', line 16

def client_secret
  @client_secret
end

Instance Method Details

#search(options = {}) ⇒ Hash

Search for NOTAMs based on various criteria

Parameters:

  • options (Hash) (defaults to: {}) —

    Search criteria parameters

Options Hash (options):

  • :response_format (String) —

    Format of the response (‘aixm’, ‘geoJson’, or ‘aidap’) (default: ‘geoJson’)

  • :icao_location (String) —

    ICAO location code (e.g., ‘KIAD’ for Dulles)

  • :domestic_location (String) —

    Domestic location code (e.g., ‘IAD’ for Dulles)

  • :notam_type (String) —

    The NOTAM type (‘N’ for New, ‘R’ for Replaced, or ‘C’ for Canceled)

  • :classification (String) —

    NOTAM classification (‘INTL’, ‘MIL’, ‘DOM’, ‘LMIL’, or ‘FDC’)

  • :notam_number (String) —

    The NOTAM number (e.g., ‘CK0000/01’)

  • :effective_start_date (String) —

    The effective start date (ISO 8601 format)

  • :effective_end_date (String) —

    The effective end date (ISO 8601 format)

  • :feature_type (String) —

    Feature type (e.g., ‘RWY’, ‘TWY’, ‘AIRSPACE’, etc.)

  • :location_longitude (Float) —

    Location longitude (e.g., -151.24)

  • :location_latitude (Float) —

    Location latitude (e.g., 60.57)

  • :location_radius (Float) —

    Location radius in nautical miles (max: 100nm)

  • :last_updated_date (String) —

    Last updated date (ISO 8601 format)

  • :sort_by (String) —

    Field to sort by (e.g., ‘icaoLocation’, ‘effectiveStartDate’)

  • :sort_order (String) —

    Sort order (‘Asc’ or ‘Desc’)

  • :page_size (Integer) —

    Number of results per page (max: 1000, default: 50)

  • :page_num (Integer) —

    Page number (default: 1)

Returns:

  • (Hash) —

    NOTAM search results



53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/faa_notams/service.rb', line 53

def search(options = {})
  # Convert snake_case option keys to camelCase for the API
  params = {}
  
  # Handle response format separately (API expects 'responseFormat')
  if options[:response_format]
    params[:responseFormat] = validate_response_format(options[:response_format])
  end
  
  # Map option keys to API parameter names
  param_mapping = {
    icao_location: :icaoLocation,
    domestic_location: :domesticLocation,
    notam_type: :notamType,
    classification: :classification,
    notam_number: :notamNumber,
    effective_start_date: :effectiveStartDate,
    effective_end_date: :effectiveEndDate,
    feature_type: :featureType,
    location_longitude: :locationLongitude,
    location_latitude: :locationLatitude,
    location_radius: :locationRadius,
    last_updated_date: :lastUpdatedDate,
    sort_by: :sortBy,
    sort_order: :sortOrder,
    page_size: :pageSize,
    page_num: :pageNum
  }
  
  # Process each key and transform to camelCase for API
  param_mapping.each do |option_key, param_key|
    if options.key?(option_key)
      # Special validation for some parameters
      value = case option_key
      when :feature_type
        validate_feature_type(options[option_key])
      when :location_radius
        validate_range(options[option_key], 0.1, 100, 'location_radius')
      when :page_size
        validate_range(options[option_key], 1, 1000, 'page_size')
      when :page_num
        validate_range(options[option_key], 1, nil, 'page_num')
      when :sort_order
        validate_enum(options[option_key], %w[Asc Desc], 'sort_order')
      else
        options[option_key]
      end
      
      params[param_key] = value
    end
  end
  
  get("/search", params)
end

#search_by_airport(airport_code, options = {}) ⇒ Hash

Convenience method to search NOTAMs by airport code (ICAO or domestic)

Parameters:

  • airport_code (String) —

    Airport code (e.g., ‘KIAD’ for ICAO or ‘IAD’ for domestic)

  • options (Hash) (defaults to: {}) —

    Additional search criteria

Returns:

  • (Hash) —

    NOTAM search results



112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/faa_notams/service.rb', line 112

def search_by_airport(airport_code, options = {})
  airport_code = airport_code.to_s.upcase
  
  if airport_code.length == 3
    options[:domestic_location] = airport_code
  else
    options[:icao_location] = airport_code
  end
  
  search(options)
end

#search_by_feature(feature_type, options = {}) ⇒ Hash

Search for NOTAMs affecting a specific feature type

Parameters:

  • feature_type (String) —

    Feature type (e.g., ‘RWY’, ‘TWY’, ‘AIRSPACE’, etc.)

  • options (Hash) (defaults to: {}) —

    Additional search criteria

Returns:

  • (Hash) —

    NOTAM search results



142
143
144
145
 
# File 'lib/faa_notams/service.rb', line 142

def search_by_feature(feature_type, options = {})
  options[:feature_type] = validate_feature_type(feature_type)
  search(options)
end

#search_by_location(latitude, longitude, radius = 50, options = {}) ⇒ Hash

Search NOTAMs by geographic location (latitude/longitude and radius)

Parameters:

  • latitude (Float) —

    Location latitude

  • longitude (Float) —

    Location longitude

  • radius (Float) (defaults to: 50) —

    Search radius in nautical miles (default: 50, max: 100)

  • options (Hash) (defaults to: {}) —

    Additional search criteria

Returns:

  • (Hash) —

    NOTAM search results



130
131
132
133
134
135
136
 
# File 'lib/faa_notams/service.rb', line 130

def search_by_location(latitude, longitude, radius = 50, options = {})
  options[:location_latitude] = latitude
  options[:location_longitude] = longitude
  options[:location_radius] = radius
  
  search(options)
end