raad-apra 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b6bc8136e517bfb9132aa7ff6c43ba074e35a3f38d5044e63c251c29fc0a5760
+  data.tar.gz: 1e72ce417acfc322366ff2c8462d96ad16b83841ca76bfa87521cc66fe997398
+SHA512:
+  metadata.gz: c40dc26fad970cc0b5c405eb42f9bab99983361ff8d98133a7a94049164bd762c671a44961d509afe781d76ca8780eb41cd5f3daf56acb450faab3a14b59a70c
+  data.tar.gz: 55b33aa916533fdaa11d483b7f5bd32fa627095c9bbc754b2c6c9cd1032381a47c04907808b306ced23a7940f8cecb4e50d35dedc25d385cfce54fb98de1fbbf

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## [0.1.0] - 2025-05-01
+
+- Initial release of the FaaApra gem
+- Added support for all APRA API endpoints:
+  - Coded Instrument Flight Procedures (CIFP)
+  - Daily Digital Obstacle File (DDOF)
+  - Digital Enroute Charts (DEC)
+  - Terminal Procedures Publication (TPP)
+  - Sectional Charts
+  - Grand Canyon VFR Charts
+  - IFR Enroute Charts
+- 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,119 @@
+# FaaApra
+
+A Ruby gem for interacting with the FAA's Aeronautical Products Release API (APRA).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'faa_apra'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install faa_apra
+```
+
+## Usage
+
+First, obtain your API credentials from the [FAA External API Portal](https://external-api.faa.gov/).
+
+### Basic Usage
+
+```ruby
+require 'faa_apra'
+
+# Initialize with client credentials
+client = FaaApra.new(
+  'your_client_id',
+  'your_client_secret'
+)
+
+# Or use environment variables
+# export FAA_APRA_CLIENT_ID=your_client_id
+# export FAA_APRA_CLIENT_SECRET=your_client_secret
+client = FaaApra.new
+
+# Get Coded Instrument Flight Procedures (CIFP)
+cifp_data = client.cifp_chart
+cifp_info = client.cifp_info(edition: 'current')
+
+# Get Terminal Procedure Publication (TPP) chart
+tpp_data = client.dtpp_chart(
+  edition: 'current',
+  area: 'US',
+  format: 'all'
+)
+
+# Get Sectional Chart data
+chart_data = client.sectional_chart(
+  edition: 'current',
+  geoname: 'NEW_YORK',
+  format: 'pdf'
+)
+
+# Get IFR Enroute Chart data
+ifr_data = client.ifr_enroute_chart(
+  edition: 'current',
+  altitude: 'high',
+  format: 'pdf'
+)
+```
+
+### Available Endpoints
+
+The gem provides access to the following FAA APRA API endpoints:
+
+#### Coded Instrument Flight Procedures (CIFP)
+- `cifp_chart(edition: 'current')` - Get CIFP chart download link
+- `cifp_info(edition: 'current')` - Get CIFP edition information
+
+#### Daily Digital Obstacle File (DDOF)
+- `ddof_chart` - Get DDOF download link
+- `ddof_info` - Get DDOF edition information
+
+#### Digital Enroute Charts (DEC)
+- `dec_chart(edition: 'current')` - Get DEC chart download link
+- `dec_info(edition: 'current')` - Get DEC edition information
+
+#### Terminal Procedures Publication (TPP)
+- `dtpp_chart(edition: 'current', area: 'US', format: 'all')` - Get TPP chart download link
+- `dtpp_info(edition: 'current', area: 'US')` - Get TPP edition information
+
+#### Sectional Charts
+- `sectional_chart(edition: 'current', geoname: nil, format: 'pdf')` - Get Sectional Chart download link
+- `sectional_info(edition: 'current', geoname: nil, format: 'pdf')` - Get Sectional Chart edition information
+
+#### Grand Canyon VFR Charts
+- `grand_canyon_chart(edition: 'current', format: 'pdf')` - Get Grand Canyon VFR Chart download link
+- `grand_canyon_info(edition: 'current', format: 'pdf')` - Get Grand Canyon VFR Chart edition information
+
+#### IFR Enroute Charts
+- `ifr_enroute_chart(edition: 'current', geoname: nil, altitude:, format: 'pdf')` - Get IFR Enroute Chart download link
+- `ifr_enroute_info(edition: 'current', geoname: nil, altitude:, format: 'pdf')` - Get IFR Enroute Chart edition information
+
+## 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_apra. 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_apra/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 FaaApra project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/yourusername/faa_apra/blob/main/CODE_OF_CONDUCT.md).

data/lib/faa_apra/service.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+module FaaApra
+  # Service to interact with FAA's Aeronautic Product Release API (APRA)
+  # https://external-api.faa.gov/apra
+  #
+  # This service provides access to FAA aeronautical chart publication download endpoints
+  # including Coded Instrument Flight Procedures, Digital Enroute Charts, Terminal Procedures, and more.
+  class Service
+    BASE_URL = "https://external-api.faa.gov/apra"
+    
+    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_APRA_CLIENT_ID']
+      @client_secret = client_secret || ENV['FAA_APRA_CLIENT_SECRET']
+      
+      raise ArgumentError, "FAA APRA client_id is required" unless @client_id
+      raise ArgumentError, "FAA APRA client_secret is required" unless @client_secret
+    end
+
+    # =========================================================================
+    # Coded Instrument Flight Procedures (CIFP)
+    # =========================================================================
+    
+    # Get CIFP chart download link
+    # @param edition [String] 'current' or 'next' edition (default: 'current')
+    # @return [Hash] CIFP release data
+    def cifp_chart(edition: 'current')
+      validate_edition(edition)
+      get("/cifp/chart", { edition: edition })
+    end
+    
+    # Get CIFP edition date and edition number
+    # @param edition [String] 'current' or 'next' edition (default: 'current')
+    # @return [Hash] CIFP edition information
+    def cifp_info(edition: 'current')
+      validate_edition(edition)
+      get("/cifp/info", { edition: edition })
+    end
+
+    # =========================================================================
+    # Daily Digital Obstacle File (DDOF)
+    # =========================================================================
+    
+    # Get Daily Digital Obstacle File download link
+    # @return [Hash] DDOF release data
+    def ddof_chart
+      get("/ddof/chart")
+    end
+    
+    # Get Daily Digital Obstacle File edition information
+    # @return [Hash] DDOF edition information
+    def ddof_info
+      get("/ddof/info")
+    end
+
+    # =========================================================================
+    # Digital Enroute Charts US (DDECUS)
+    # =========================================================================
+    
+    # Get Digital Enroute Chart download link
+    # @param edition [String] 'current' or 'next' edition (default: 'current')
+    # @return [Hash] DEC release data
+    def dec_chart(edition: 'current')
+      validate_edition(edition)
+      get("/dec/chart", { edition: edition })
+    end
+    
+    # Get DEC edition date and edition number
+    # @param edition [String] 'current' or 'next' edition (default: 'current')
+    # @return [Hash] DEC edition information
+    def dec_info(edition: 'current')
+      validate_edition(edition)
+      get("/dec/info", { edition: edition })
+    end
+
+    # =========================================================================
+    # US Terminal Procedures Publication (TPP)
+    # =========================================================================
+    
+    # Get Terminal Procedure Publication chart download information
+    # @param edition [String] 'current' or 'next' edition (default: 'current')
+    # @param area [String] geographic area, 'US' or state name (default: 'US')
+    # @param format [String] 'all', 'changes', or 'xml' format (default: 'all')
+    # @return [Hash] TPP release data
+    def dtpp_chart(edition: 'current', area: 'US', format: 'all')
+      validate_edition(edition)
+      validate_format(format, %w[all changes xml])
+      
+      get("/dtpp/chart", { 
+        edition: edition,
+        area: area,
+        format: format
+      })
+    end
+    
+    # Get Terminal Procedure Publication chart edition information
+    # @param edition [String] 'current' or 'next' edition (default: 'current')
+    # @param area [String] geographic area, 'US' or state name (default: 'US')
+    # @return [Hash] TPP edition information
+    def dtpp_info(edition: 'current', area: 'US')
+      validate_edition(edition)
+      
+      get("/dtpp/info", {
+        edition: edition,
+        area: area
+      })
+    end
+
+    # =========================================================================
+    # Sectional Charts
+    # =========================================================================
+    
+    # Get Sectional Chart download link
+    # @param edition [String] 'current' or 'next' edition (default: 'current')
+    # @param geoname [String] geographic name of the sectional chart
+    # @param format [String] 'tiff' or 'pdf' format (default: 'pdf')
+    # @return [Hash] Sectional Chart release data
+    def sectional_chart(edition: 'current', geoname: nil, format: 'pdf')
+      validate_edition(edition)
+      validate_format(format, %w[tiff pdf])
+      
+      params = { edition: edition, format: format }
+      params[:geoname] = geoname if geoname
+      
+      get("/sectional/chart", params)
+    end
+    
+    # Get Sectional Chart edition information
+    # @param edition [String] 'current' or 'next' edition (default: 'current')
+    # @param geoname [String] geographic name of the sectional chart
+    # @param format [String] 'tiff' or 'pdf' format (default: 'pdf')
+    # @return [Hash] Sectional Chart edition information
+    def sectional_info(edition: 'current', geoname: nil, format: 'pdf')
+      validate_edition(edition)
+      validate_format(format, %w[tiff pdf])
+      
+      params = { edition: edition, format: format }
+      params[:geoname] = geoname if geoname
+      
+      get("/sectional/info", params)
+    end
+
+    # =========================================================================
+    # Grand Canyon VFR Charts
+    # =========================================================================
+    
+    # Get Grand Canyon VFR Chart download link
+    # @param edition [String] 'current' or 'next' edition (default: 'current')
+    # @param format [String] 'tiff' or 'pdf' format (default: 'pdf')
+    # @return [Hash] Grand Canyon VFR Chart release data
+    def grand_canyon_chart(edition: 'current', format: 'pdf')
+      validate_edition(edition)
+      validate_format(format, %w[tiff pdf])
+      
+      get("/grandcanyon/chart", { edition: edition, format: format })
+    end
+    
+    # Get Grand Canyon VFR Chart edition information
+    # @param edition [String] 'current' or 'next' edition (default: 'current')
+    # @param format [String] 'tiff' or 'pdf' format (default: 'pdf')
+    # @return [Hash] Grand Canyon VFR Chart edition information
+    def grand_canyon_info(edition: 'current', format: 'pdf')
+      validate_edition(edition)
+      validate_format(format, %w[tiff pdf])
+      
+      get("/grandcanyon/info", { edition: edition, format: format })
+    end
+
+    # =========================================================================
+    # IFR Enroute Charts
+    # =========================================================================
+    
+    # Get IFR Enroute Chart download link
+    # @param edition [String] 'current' or 'next' edition (default: 'current')
+    # @param geoname [String] geographic name of the chart
+    # @param altitude [String] 'high' or 'low' altitude (required)
+    # @param format [String] 'tiff' or 'pdf' format (default: 'pdf')
+    # @return [Hash] IFR Enroute Chart release data
+    def ifr_enroute_chart(edition: 'current', geoname: nil, altitude:, format: 'pdf')
+      validate_edition(edition)
+      validate_altitude(altitude)
+      validate_format(format, %w[tiff pdf])
+      
+      params = { 
+        edition: edition,
+        altitude: altitude.downcase,
+        format: format
+      }
+      params[:geoname] = geoname if geoname
+      
+      get("/ifr/enroute/chart", params)
+    end
+    
+    # Get IFR Enroute Chart edition information
+    # @param edition [String] 'current' or 'next' edition (default: 'current')
+    # @param geoname [String] geographic name of the chart
+    # @param altitude [String] 'high' or 'low' altitude (required)
+    # @param format [String] 'tiff' or 'pdf' format (default: 'pdf')
+    # @return [Hash] IFR Enroute Chart edition information
+    def ifr_enroute_info(edition: 'current', geoname: nil, altitude:, format: 'pdf')
+      validate_edition(edition)
+      validate_altitude(altitude)
+      validate_format(format, %w[tiff pdf])
+      
+      params = {
+        edition: edition,
+        altitude: altitude.downcase,
+        format: format
+      }
+      params[:geoname] = geoname if geoname
+      
+      get("/ifr/enroute/info", params)
+    end
+
+    # =========================================================================
+    # Helper Methods
+    # =========================================================================
+
+    private
+
+    # Make a GET request to the APRA 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 edition parameter
+    # @param edition [String] Edition value to validate
+    # @raise [ArgumentError] If edition is not valid
+    def validate_edition(edition)
+      unless ['current', 'next'].include?(edition.to_s.downcase)
+        raise ArgumentError, "Invalid edition. Must be 'current' or 'next'"
+      end
+    end
+    
+    # Validate format parameter
+    # @param format [String] Format value to validate
+    # @param allowed_values [Array<String>] Allowed format values
+    # @raise [ArgumentError] If format is not valid
+    def validate_format(format, allowed_values)
+      unless allowed_values.include?(format.to_s.downcase)
+        raise ArgumentError, "Invalid format. Must be one of: #{allowed_values.join(', ')}"
+      end
+    end
+    
+    # Validate altitude parameter
+    # @param altitude [String] Altitude value to validate
+    # @raise [ArgumentError] If altitude is not valid
+    def validate_altitude(altitude)
+      unless ['high', 'low'].include?(altitude.to_s.downcase)
+        raise ArgumentError, "Invalid altitude. Must be 'high' or 'low'"
+      end
+    end
+  end
+end

data/lib/faa_apra/version.rb

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

data/lib/faa_apra.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "faa_apra/version"
+require_relative "faa_apra/service"
+
+# FaaApra - Ruby gem to interact with FAA's Aeronautic Product Release API (APRA)
+# https://external-api.faa.gov/apra
+#
+# This gem provides access to FAA aeronautical chart publication download endpoints
+# including Coded Instrument Flight Procedures, Digital Enroute Charts, Terminal Procedures, and more.
+module FaaApra
+  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 [FaaApra::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-apra
+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 APRA API, which provides access
+  to aeronautical chart publications and download endpoints.
+email:
+- jp@raad.com
+- jpsilvashy@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/faa_apra.rb
+- lib/faa_apra/service.rb
+- lib/faa_apra/version.rb
+homepage: https://github.com/raad-labs/apra
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/raad-labs/apra
+  source_code_uri: https://github.com/raad-labs/apra
+  changelog_uri: https://github.com/raad-labs/apra/blob/main/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/raad-apra
+  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 Aeronautical Products Release API (APRA)
+test_files: []