raad-notams 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3ad7f10b948f4896bdba3b4c377c4e307ec9a2ea2409d8405faccd29d9ea1798
+  data.tar.gz: 4a312b0b092f60cd90f45dda6fe1915143730dad9b3029f4f7f671b5dcb57fe1
+SHA512:
+  metadata.gz: e0def67e4235df97cb1ea33353a62ff45543a3ec6b99b0c6e0046e096933db4fa1bc4223d57ab4df875e8703f8e944c6e842a002303dc8b2e9537396cafbd5dd
+  data.tar.gz: 44e28fb891645cadb27ea7f282d2dc85e6c1d9589dcb5315baf6c12bf873b6ab66fd16b3cd6e605c0d008f2ce370155352f6bd674dad6ce976a111aba14af68f

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [0.1.0] - 2025-05-01
+
+- Initial release of the FaaNotams gem
+- Added support for all NOTAM API endpoints
+- Implemented search, search_by_airport, search_by_location, and search_by_feature methods
+- Added validation for API parameters
+- Set up basic documentation

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,102 @@
+# FaaNotams
+
+A Ruby gem for interacting with the FAA's Notice to Airmen (NOTAM) API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'faa_notams'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install faa_notams
+```
+
+## Usage
+
+First, obtain your API credentials from the [FAA External API Portal](https://external-api.faa.gov/).
+
+### Basic Usage
+
+```ruby
+require 'faa_notams'
+
+# Initialize with client credentials
+client = FaaNotams.new(
+  'your_client_id',
+  'your_client_secret'
+)
+
+# Or use environment variables
+# export FAA_NOTAM_CLIENT_ID=your_client_id
+# export FAA_NOTAM_CLIENT_SECRET=your_client_secret
+client = FaaNotams.new
+
+# Search for NOTAMs
+results = client.search(
+  icao_location: 'KIAD',
+  page_size: 50,
+  page_num: 1
+)
+
+# Search by airport
+results = client.search_by_airport('KIAD')
+# or domestic code
+results = client.search_by_airport('IAD')
+
+# Search by geographic location
+results = client.search_by_location(38.9445, -77.4558, 50)
+
+# Search by feature type
+results = client.search_by_feature('RWY')
+```
+
+### Available Search Parameters
+
+The `search` method accepts the following parameters:
+
+- `:response_format` - Format of the response ('aixm', 'geoJson', or 'aidap')
+- `:icao_location` - ICAO location code (e.g., 'KIAD' for Dulles)
+- `:domestic_location` - Domestic location code (e.g., 'IAD' for Dulles)
+- `:notam_type` - The NOTAM type ('N' for New, 'R' for Replaced, or 'C' for Canceled)
+- `:classification` - NOTAM classification ('INTL', 'MIL', 'DOM', 'LMIL', or 'FDC')
+- `:notam_number` - The NOTAM number (e.g., 'CK0000/01')
+- `:effective_start_date` - The effective start date (ISO 8601 format)
+- `:effective_end_date` - The effective end date (ISO 8601 format)
+- `:feature_type` - Feature type (e.g., 'RWY', 'TWY', 'AIRSPACE', etc.)
+- `:location_longitude` - Location longitude (e.g., -151.24)
+- `:location_latitude` - Location latitude (e.g., 60.57)
+- `:location_radius` - Location radius in nautical miles (max: 100nm)
+- `:last_updated_date` - Last updated date (ISO 8601 format)
+- `:sort_by` - Field to sort by (e.g., 'icaoLocation', 'effectiveStartDate')
+- `:sort_order` - Sort order ('Asc' or 'Desc')
+- `:page_size` - Number of results per page (max: 1000, default: 50)
+- `:page_num` - Page number (default: 1)
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/faa_notams. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/yourusername/faa_notams/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the FaaNotams project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/yourusername/faa_notams/blob/main/CODE_OF_CONDUCT.md).

data/lib/faa_notams/service.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+module FaaNotams
+  # Service to interact with FAA's Notice to Airmen (NOTAM) API
+  # https://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).
+  class Service
+    BASE_URL = "https://external-api.faa.gov/notamapi/v1"
+    
+    attr_reader :client_id, :client_secret
+
+    # Initialize the service with FAA API credentials
+    # @param client_id [String] FAA API client ID
+    # @param client_secret [String] FAA API client secret
+    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
+
+    # =========================================================================
+    # NOTAM API Endpoints
+    # =========================================================================
+    
+    # Search for NOTAMs based on various criteria
+    # @param options [Hash] Search criteria parameters
+    # @option options [String] :response_format Format of the response ('aixm', 'geoJson', or 'aidap') (default: 'geoJson')
+    # @option options [String] :icao_location ICAO location code (e.g., 'KIAD' for Dulles)
+    # @option options [String] :domestic_location Domestic location code (e.g., 'IAD' for Dulles)
+    # @option options [String] :notam_type The NOTAM type ('N' for New, 'R' for Replaced, or 'C' for Canceled)
+    # @option options [String] :classification NOTAM classification ('INTL', 'MIL', 'DOM', 'LMIL', or 'FDC')
+    # @option options [String] :notam_number The NOTAM number (e.g., 'CK0000/01')
+    # @option options [String] :effective_start_date The effective start date (ISO 8601 format)
+    # @option options [String] :effective_end_date The effective end date (ISO 8601 format)
+    # @option options [String] :feature_type Feature type (e.g., 'RWY', 'TWY', 'AIRSPACE', etc.)
+    # @option options [Float] :location_longitude Location longitude (e.g., -151.24)
+    # @option options [Float] :location_latitude Location latitude (e.g., 60.57)
+    # @option options [Float] :location_radius Location radius in nautical miles (max: 100nm)
+    # @option options [String] :last_updated_date Last updated date (ISO 8601 format)
+    # @option options [String] :sort_by Field to sort by (e.g., 'icaoLocation', 'effectiveStartDate')
+    # @option options [String] :sort_order Sort order ('Asc' or 'Desc')
+    # @option options [Integer] :page_size Number of results per page (max: 1000, default: 50)
+    # @option options [Integer] :page_num Page number (default: 1)
+    # @return [Hash] NOTAM search results
+    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
+    
+    # Convenience method to search NOTAMs by airport code (ICAO or domestic)
+    # @param airport_code [String] Airport code (e.g., 'KIAD' for ICAO or 'IAD' for domestic)
+    # @param options [Hash] Additional search criteria
+    # @return [Hash] NOTAM search results
+    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 NOTAMs by geographic location (latitude/longitude and radius)
+    # @param latitude [Float] Location latitude
+    # @param longitude [Float] Location longitude
+    # @param radius [Float] Search radius in nautical miles (default: 50, max: 100)
+    # @param options [Hash] Additional search criteria
+    # @return [Hash] NOTAM search results
+    def search_by_location(latitude, longitude, radius = 50, options = {})
+      options[:location_latitude] = latitude
+      options[:location_longitude] = longitude
+      options[:location_radius] = radius
+      
+      search(options)
+    end
+    
+    # Search for NOTAMs affecting a specific feature type
+    # @param feature_type [String] Feature type (e.g., 'RWY', 'TWY', 'AIRSPACE', etc.)
+    # @param options [Hash] Additional search criteria
+    # @return [Hash] NOTAM search results
+    def search_by_feature(feature_type, options = {})
+      options[:feature_type] = validate_feature_type(feature_type)
+      search(options)
+    end
+
+    # =========================================================================
+    # Helper Methods
+    # =========================================================================
+
+    private
+
+    # Make a GET request to the NOTAM API
+    # @param path [String] API endpoint path
+    # @param params [Hash] Query parameters
+    # @return [Hash] Parsed JSON response
+    def get(path, params = {})
+      uri = URI.parse("#{BASE_URL}#{path}")
+      uri.query = URI.encode_www_form(params) if params.any?
+      
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      
+      request = Net::HTTP::Get.new(uri)
+      request['client_id'] = @client_id
+      request['client_secret'] = @client_secret
+      request['Accept'] = 'application/json'
+      
+      response = http.request(request)
+      handle_response(response)
+    end
+    
+    # Handle API response
+    # @param response [Net::HTTPResponse] HTTP response from the API
+    # @return [Hash] Parsed JSON response
+    # @raise [RuntimeError] If the response is not successful
+    def handle_response(response)
+      case response.code.to_i
+      when 200
+        JSON.parse(response.body)
+      when 400
+        raise "Bad request: #{response.body}"
+      when 401
+        raise "Unauthorized: Invalid API credentials"
+      when 404
+        raise "Not found: Requested resource not available"
+      when 500
+        raise "Internal server error: #{response.body}"
+      else
+        raise "Unexpected response (#{response.code}): #{response.body}"
+      end
+    end
+    
+    # Validate response format
+    # @param format [String] Format value to validate
+    # @return [String] Validated format
+    # @raise [ArgumentError] If format is not valid
+    def validate_response_format(format)
+      valid_formats = %w[aixm geoJson aidap]
+      format = format.to_s.downcase
+      
+      # Special handling for 'geojson' vs 'geoJson' formats
+      format = 'geoJson' if format == 'geojson'
+      
+      unless valid_formats.include?(format)
+        raise ArgumentError, "Invalid response format. Must be one of: #{valid_formats.join(', ')}"
+      end
+      
+      format
+    end
+    
+    # Validate that a value is within a specific range
+    # @param value [Numeric] Value to validate
+    # @param min [Numeric] Minimum allowed value
+    # @param max [Numeric] Maximum allowed value (or nil for no upper limit)
+    # @param param_name [String] Parameter name for error messages
+    # @return [Numeric] Validated value
+    # @raise [ArgumentError] If value is not within range
+    def validate_range(value, min, max, param_name)
+      value = value.to_f
+      if value < min || (max && value > max)
+        max_msg = max ? " and #{max}" : ""
+        raise ArgumentError, "Invalid #{param_name}. Must be between #{min}#{max_msg}."
+      end
+      value
+    end
+    
+    # Validate that a value is within an enumeration
+    # @param value [String] Value to validate
+    # @param allowed_values [Array<String>] Allowed values
+    # @param param_name [String] Parameter name for error messages
+    # @return [String] Validated value
+    # @raise [ArgumentError] If value is not in allowed values
+    def validate_enum(value, allowed_values, param_name)
+      value = value.to_s
+      unless allowed_values.include?(value)
+        raise ArgumentError, "Invalid #{param_name}. Must be one of: #{allowed_values.join(', ')}"
+      end
+      value
+    end
+    
+    # Validate feature type
+    # @param feature_type [String] Feature type to validate
+    # @return [String] Validated feature type
+    # @raise [ArgumentError] If feature type is not valid
+    def validate_feature_type(feature_type)
+      allowed_feature_types = %w[
+        RWY TWY APRON AD OBST NAV COM SVC AIRSPACE ODP SID STAR 
+        CHART DATA DVA IAP VFP ROUTE SPECIAL SECURITY MILITARY INTERNATIONAL
+      ]
+      
+      validate_enum(feature_type, allowed_feature_types, 'feature_type')
+    end
+  end
+end

data/lib/faa_notams/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FaaNotams
+  VERSION = "0.1.0"
+end

data/lib/faa_notams.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "faa_notams/version"
+require_relative "faa_notams/service"
+
+# FaaNotams - Ruby gem to interact with FAA's Notice to Airmen (NOTAM) API
+# https://external-api.faa.gov/notamapi
+#
+# This gem provides access to FAA's NOTAM API, which contains real-time notification
+# of any change in the National Airspace System (NAS).
+module FaaNotams
+  class Error < StandardError; end
+  
+  # Convenience method to create a new service instance
+  # @param client_id [String] FAA API client ID
+  # @param client_secret [String] FAA API client secret
+  # @return [FaaNotams::Service] A new service instance
+  def self.new(client_id = nil, client_secret = nil)
+    Service.new(client_id, client_secret)
+  end
+end

metadata

@@ -0,0 +1,151 @@
+--- !ruby/object:Gem::Specification
+name: raad-notams
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- JP Silvashy
+bindir: exe
+cert_chain: []
+date: 2025-05-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.14'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: A Ruby gem to interact with the FAA's NOTAM API, which provides real-time
+  notifications of changes in the National Airspace System (NAS).
+email:
+- jp@raad.com
+- jpsilvashy@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/faa_notams.rb
+- lib/faa_notams/service.rb
+- lib/faa_notams/version.rb
+homepage: https://github.com/raad-labs/notams
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/raad-labs/notams
+  source_code_uri: https://github.com/raad-labs/notams
+  changelog_uri: https://github.com/raad-labs/notams/blob/main/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/raad-notams
+  allowed_push_host: https://rubygems.org
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.3
+specification_version: 4
+summary: Ruby wrapper for the FAA Notice to Airmen (NOTAM) API
+test_files: []