raad-adip 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d45ba15fe2dcf22492b860c54c3b931ce1dca1fea322e5390136562b9ec0c8d0
+  data.tar.gz: a93fa94f7c589f29cc665a9774ba23009c4420bcbab7012d032ae54c4786ca0c
+SHA512:
+  metadata.gz: 29e04bbdca6ac02e7e8534d316f26a5bbfd9d4b3788a941c15e6aadea2fee4fb742ee881c32e8d150f4943ad46b0a8f4246cb071a956383c89987bc9b6268852
+  data.tar.gz: 36c6d55050b2720c98d7a65548d935980a094b8c19543a070e46919b319fb023389338bf779df10a52b0e79a75d9fa95e4eec4b27f196a45da81857a93a12808

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [0.1.0] - 2025-05-01
+
+- Initial release of the FaaAdip gem
+- Added support for the following ADIP API endpoints:
+  - Airport search and retrieval
+  - Runway information
+  - Weather data (METAR, TAF)
+  - Facility information
+  - Nearby airport search
+- 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,120 @@
+# FaaAdip
+
+A Ruby gem for interacting with the FAA's Airport Data & Information Portal (ADIP) API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'faa_adip'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install faa_adip
+```
+
+## Usage
+
+First, obtain your API credentials from the [FAA External API Portal](https://external-api.faa.gov/).
+
+### Basic Usage
+
+```ruby
+require 'faa_adip'
+
+# Initialize with client credentials
+client = FaaAdip.new(
+  'your_client_id',
+  'your_client_secret'
+)
+
+# Or use environment variables
+# export FAA_ADIP_CLIENT_ID=your_client_id
+# export FAA_ADIP_CLIENT_SECRET=your_client_secret
+client = FaaAdip.new
+
+# Search for airports
+results = client.search_airports(
+  state: 'VA',
+  facility_use: 'PUBLIC',
+  page_size: 20
+)
+
+# Get information for a specific airport
+airport = client.get_airport('KIAD')
+
+# Get runway information
+runways = client.get_runways('KIAD')
+
+# Get weather information
+metar = client.get_metar('KIAD')
+taf = client.get_taf('KIAD')
+
+# Find nearby airports
+nearby = client.get_nearby_airports('KIAD', 30, facility_use: 'PUBLIC')
+```
+
+### Available Search Parameters
+
+The `search_airports` method accepts the following parameters:
+
+- `:airport_id` - Airport identifier (e.g., 'KIAD')
+- `:site_number` - FAA site number
+- `:loc_id` - Location identifier
+- `:state` - Two-letter state code
+- `:city` - City name
+- `:county` - County name
+- `:facility_name` - Airport name or partial name
+- `:facility_use` - 'PUBLIC', 'PRIVATE', or 'MILITARY'
+- `:latitude` - Latitude coordinate
+- `:longitude` - Longitude coordinate
+- `:radius` - Search radius in nautical miles (when used with lat/lon)
+- `:page_size` - Number of results per page (default: 20, max: 100)
+- `:page_num` - Page number (default: 1)
+
+### Endpoints
+
+The gem provides access to the following endpoints:
+
+#### Airport Information
+- `search_airports(options = {})` - Search for airports using various criteria
+- `get_airport(airport_id)` - Get detailed information for a specific airport
+
+#### Runway Data
+- `get_runways(airport_id)` - Get runway information for a specific airport
+- `get_runway(airport_id, runway_id)` - Get detailed information for a specific runway
+
+#### Weather Data
+- `get_metar(airport_id)` - Get METAR (current weather) data for an airport
+- `get_taf(airport_id)` - Get TAF (forecast) data for an airport
+
+#### Facility Data
+- `get_facilities(airport_id)` - Get facility information for an airport
+- `get_nearby_airports(airport_id, radius = 20, options = {})` - Find airports near a specific airport
+
+## 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_adip. 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_adip/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 FaaAdip project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/yourusername/faa_adip/blob/main/CODE_OF_CONDUCT.md).

data/lib/faa_adip/service.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+module FaaAdip
+  # Service to interact with FAA's Airport Data & Information Portal (ADIP) API
+  # https://external-api.faa.gov/adip
+  #
+  # This service provides access to FAA's ADIP API, which contains information about airports,
+  # including facilities, runways, and other airport data.
+  class Service
+    BASE_URL = "https://external-api.faa.gov/adip/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_ADIP_CLIENT_ID']
+      @client_secret = client_secret || ENV['FAA_ADIP_CLIENT_SECRET']
+      
+      raise ArgumentError, "FAA ADIP client_id is required" unless @client_id
+      raise ArgumentError, "FAA ADIP client_secret is required" unless @client_secret
+    end
+
+    # =========================================================================
+    # Airport Search Endpoints
+    # =========================================================================
+    
+    # Search for airports based on various criteria
+    # @param options [Hash] Search criteria parameters
+    # @option options [String] :airport_id Airport identifier (e.g., 'KIAD')
+    # @option options [String] :site_number FAA site number
+    # @option options [String] :loc_id Location identifier
+    # @option options [String] :state Two-letter state code
+    # @option options [String] :city City name
+    # @option options [String] :county County name
+    # @option options [String] :facility_name Airport name or partial name
+    # @option options [String] :facility_use 'PUBLIC', 'PRIVATE', or 'MILITARY'
+    # @option options [Float] :latitude Latitude coordinate
+    # @option options [Float] :longitude Longitude coordinate
+    # @option options [Float] :radius Search radius in nautical miles (when used with lat/lon)
+    # @option options [Integer] :page_size Number of results per page (default: 20, max: 100)
+    # @option options [Integer] :page_num Page number (default: 1)
+    # @return [Hash] Airport search results
+    def search_airports(options = {})
+      params = {}
+      
+      # Map option keys to API parameter names
+      param_mapping = {
+        airport_id: :airportId,
+        site_number: :siteNumber,
+        loc_id: :locId,
+        state: :state,
+        city: :city,
+        county: :county,
+        facility_name: :facilityName,
+        facility_use: :facilityUse,
+        latitude: :latitude,
+        longitude: :longitude,
+        radius: :radius,
+        page_size: :pageSize,
+        page_num: :pageNum
+      }
+      
+      # Process each option
+      param_mapping.each do |option_key, param_key|
+        if options.key?(option_key)
+          # Special validation for parameters
+          value = case option_key
+          when :facility_use
+            validate_enum(options[option_key], %w[PUBLIC PRIVATE MILITARY], 'facility_use')
+          when :radius
+            validate_range(options[option_key], 0.1, 100, 'radius')
+          when :page_size
+            validate_range(options[option_key], 1, 100, 'page_size').to_i
+          when :page_num
+            validate_range(options[option_key], 1, nil, 'page_num').to_i
+          else
+            options[option_key]
+          end
+          
+          params[param_key] = value
+        end
+      end
+      
+      get("/airports", params)
+    end
+    
+    # Get detailed information for a specific airport by its ID
+    # @param airport_id [String] Airport identifier (e.g., 'KIAD')
+    # @return [Hash] Detailed airport information
+    def get_airport(airport_id)
+      get("/airports/#{URI.encode_www_form_component(airport_id)}")
+    end
+    
+    # =========================================================================
+    # Runway Data Endpoints
+    # =========================================================================
+    
+    # Get runway information for a specific airport
+    # @param airport_id [String] Airport identifier (e.g., 'KIAD')
+    # @return [Hash] Runway information for the airport
+    def get_runways(airport_id)
+      get("/airports/#{URI.encode_www_form_component(airport_id)}/runways")
+    end
+    
+    # Get detailed information for a specific runway
+    # @param airport_id [String] Airport identifier (e.g., 'KIAD')
+    # @param runway_id [String] Runway identifier (e.g., '01/19')
+    # @return [Hash] Detailed runway information
+    def get_runway(airport_id, runway_id)
+      get("/airports/#{URI.encode_www_form_component(airport_id)}/runways/#{URI.encode_www_form_component(runway_id)}")
+    end
+    
+    # =========================================================================
+    # Weather Data Endpoints
+    # =========================================================================
+    
+    # Get METAR (Meteorological Aerodrome Report) data for a specific airport
+    # @param airport_id [String] Airport identifier (e.g., 'KIAD')
+    # @return [Hash] METAR data for the airport
+    def get_metar(airport_id)
+      get("/airports/#{URI.encode_www_form_component(airport_id)}/weather/metar")
+    end
+    
+    # Get TAF (Terminal Aerodrome Forecast) data for a specific airport
+    # @param airport_id [String] Airport identifier (e.g., 'KIAD')
+    # @return [Hash] TAF data for the airport
+    def get_taf(airport_id)
+      get("/airports/#{URI.encode_www_form_component(airport_id)}/weather/taf")
+    end
+    
+    # =========================================================================
+    # Facility Data Endpoints
+    # =========================================================================
+    
+    # Get facility information for a specific airport
+    # @param airport_id [String] Airport identifier (e.g., 'KIAD')
+    # @return [Hash] Facility information for the airport
+    def get_facilities(airport_id)
+      get("/airports/#{URI.encode_www_form_component(airport_id)}/facilities")
+    end
+    
+    # Get nearby airports within a specified radius
+    # @param airport_id [String] Airport identifier (e.g., 'KIAD')
+    # @param radius [Float] Search radius in nautical miles (default: 20, max: 100)
+    # @param options [Hash] Additional filter options
+    # @option options [String] :facility_use Filter by facility use ('PUBLIC', 'PRIVATE', 'MILITARY')
+    # @return [Hash] List of nearby airports
+    def get_nearby_airports(airport_id, radius = 20, options = {})
+      params = { radius: validate_range(radius, 0.1, 100, 'radius') }
+      
+      if options[:facility_use]
+        params[:facilityUse] = validate_enum(options[:facility_use], %w[PUBLIC PRIVATE MILITARY], 'facility_use')
+      end
+      
+      get("/airports/#{URI.encode_www_form_component(airport_id)}/nearby", params)
+    end
+
+    # =========================================================================
+    # Helper Methods
+    # =========================================================================
+
+    private
+
+    # Make a GET request to the ADIP 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 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.upcase
+      unless allowed_values.include?(value)
+        raise ArgumentError, "Invalid #{param_name}. Must be one of: #{allowed_values.join(', ')}"
+      end
+      value
+    end
+  end
+end

data/lib/faa_adip/version.rb

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

data/lib/faa_adip.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "faa_adip/version"
+require_relative "faa_adip/service"
+
+# FaaAdip - Ruby gem to interact with FAA's Airport Data & Information Portal (ADIP) API
+# https://external-api.faa.gov/adip
+#
+# This gem provides access to FAA's ADIP API, which contains information about airports,
+# including facilities, runways, and other airport data.
+module FaaAdip
+  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 [FaaAdip::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-adip
+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 ADIP API, which provides access
+  to airport information, runways, facilities, and weather data.
+email:
+- jp@raad.com
+- jpsilvashy@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/faa_adip.rb
+- lib/faa_adip/service.rb
+- lib/faa_adip/version.rb
+homepage: https://github.com/raad-labs/adip
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/raad-labs/adip
+  source_code_uri: https://github.com/raad-labs/adip
+  changelog_uri: https://github.com/raad-labs/adip/blob/main/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/raad-adip
+  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 Airport Data & Information Portal (ADIP) API
+test_files: []