fcc_reboot 0.1

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in gem_template.gemspec
+gemspec

data/LICENSE.md

@@ -0,0 +1,10 @@
+Copyright (c) 2011, Code for America
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+* Neither the name of Code for America nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.mkd

@@ -0,0 +1,87 @@
+FCC Reboot
+=======
+A Ruby wrapper for the FCC Reboot APIs.
+
+Does your project or organization use this gem?
+------------------------------------------
+Add it to the [apps](http://github.com/cfalabs/fcc_reboot/wiki/apps) wiki!
+
+Installation
+------------
+    $ [sudo] gem install fcc_reboot
+
+Usage Examples
+--------------
+    require 'fcc_reboot'
+        
+    # Provide speed test statistics for a US County given the passed Latitude and Longitude
+    FccReboot.broadband_test(:latitude => '38.0', :longitude => '-77.5')
+    
+    # Returns a list of the frequency bands 
+    FccReboot.get_spectrum_bands(:frequencyFrom=>'226', :frequencyTo => '900')
+    
+    # Provide high level overview of who owns spectrum across the country within the 225 MHz to 3700 MHz frequency
+    FccReboot.get_spectrum_licenses(:name=> 'AT', :radioservice=>'Cellular')
+    
+    # Provide census block info for the given latitude and longitude
+    FccReboot.find_census_block(:latitude => '38.0', :longitude => '-77.5')
+    
+    # Provide FRN list for the state of Illinois
+    FccReboot.frn_getlist(:stateCode => 'IL', :multi => 'No')
+    
+    # Provide FRN info for Cygnus Telecommunications Corporation (FRN number 0017855545)
+    FccReboot.find_census_block(:frn => '0017855545')
+    
+    # Returns the number of licenses up for renewal in a given month for Sprint Nextel.
+    FccReboot.get_issued(:commonName=> 'Sprint Nextel')
+    
+    # Returns the counts and percent distribution of active licenses by entity type
+    FccReboot.get_renewals()
+    
+    # Provide number of licenses that were issued by the Commission on a yearly basis
+    FccReboot.get_licenses(:searchValue => 'Verizon Wireless')
+    
+    # Returns the license counts and percent distribution by status.
+    FccReboot.get_statuses(:commonName => 'Sprint Nextel')
+    
+Contributing
+------------
+In the spirit of [free software](http://www.fsf.org/licensing/essays/free-sw.html), **everyone** is encouraged to help improve this project.
+
+Here are some ways *you* can contribute:
+
+* by using alpha, beta, and prerelease versions
+* by reporting bugs
+* by suggesting new features
+* by writing or editing documentation
+* by writing specifications
+* by writing code (**no patch is too small**: fix typos, add comments, clean up inconsistent whitespace)
+* by refactoring code
+* by resolving [issues](http://github.com/cfalabs/fcc_reboot/issues)
+* by reviewing patches
+
+Submitting an Issue
+-------------------
+We use the [GitHub issue tracker](http://github.com/cfalabs/fcc_reboot/issues) to track bugs and
+features. Before submitting a bug report or feature request, check to make sure it hasn't already
+been submitted. You can indicate support for an existing issuse by voting it up. When submitting a
+bug report, please include a [Gist](http://gist.github.com/) that includes a stack trace and any
+details that may be necessary to reproduce the bug, including your gem version, Ruby version, and
+operating system. Ideally, a bug report should include a pull request with failing specs.
+
+Submitting a Pull Request
+-------------------------
+1. Fork the project.
+2. Create a topic branch.
+3. Implement your feature or bug fix.
+4. Add documentation for your feature or bug fix.
+5. Run <tt>bundle exec rake doc:yard</tt>. If your changes are not 100% documented, go back to step 4.
+6. Add specs for your feature or bug fix.
+7. Run <tt>bundle exec rake spec</tt>. If your changes are not 100% covered, go back to step 6.
+8. Commit and push your changes.
+9. Submit a pull request. Please do not include changes to the gemspec, version, or history file. (If you want to create your own version for some reason, please do so in a separate commit.)
+
+Copyright
+---------
+Copyright (c) 2010 Code for America Laboratories
+See [LICENSE](https://github.com/cfalabs/fcc_reboot/blob/master/LICENSE.mkd) for details.

data/Rakefile

@@ -0,0 +1,16 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+task :test => :spec
+
+require 'yard'
+namespace :doc do
+  YARD::Rake::YardocTask.new do |task|
+    task.files   = ['LICENSE.md', 'lib/**/*.rb']
+    task.options = ['--markup', 'markdown']
+  end
+end

data/fcc_ruby_gem.gemspec

@@ -0,0 +1,38 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "fcc_reboot/version"
+
+Gem::Specification.new do |s|
+  s.name        = "fcc_reboot"
+  s.version     = FccReboot::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors      = ["Dan Melton", "Javier"]
+  s.email       = "info@codeforamerica.org"
+  s.homepage    = ""
+  s.summary     = %q{FCC API Wrapper}
+  s.description = %q{Wrapper for FCC API}
+
+  s.rubyforge_project = "fcc_reboot"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency('ZenTest', '~> 4.5')
+  s.add_development_dependency('maruku', '~> 0.6')
+  s.add_development_dependency('rake', '~> 0.8')
+  s.add_development_dependency('rspec', '~> 2.5')
+  s.add_development_dependency('simplecov', '~> 0.4')
+  s.add_development_dependency('yard', '~> 0.6')
+  s.add_development_dependency('nokogiri', '~> 1.4')
+  s.add_development_dependency('webmock', '~> 1.5')
+
+  s.add_runtime_dependency('hashie', '~> 1.0.0')
+  s.add_runtime_dependency('faraday', '~> 0.6.0')
+  s.add_runtime_dependency('faraday_middleware', '~> 0.6.0')
+  s.add_runtime_dependency('multi_json', '~> 0.0.5')
+  s.add_runtime_dependency('multi_xml', '~> 0.2.0')
+
+  s.add_dependency('json', '~>1.5.1')
+end

data/lib/fcc_reboot.rb

@@ -0,0 +1,47 @@
+require ::File.expand_path('../fcc_reboot/version', __FILE__)
+require ::File.expand_path('../fcc_reboot/configuration.rb', __FILE__)
+require ::File.expand_path('../fcc_reboot/client', __FILE__)
+
+module FccReboot
+  extend Configuration
+
+  # Alias for FccReboot::Client.new
+  #
+  # @return [FccReboot::Client]
+  def self.client(options={})
+    FccReboot::Client.new(options)
+  end
+
+  # Delegate to FccReboot::Client
+  def self.method_missing(method, *args, &block)
+    return super unless client.respond_to?(method)
+    client.send(method, *args, &block)
+  end
+
+  # Custom error class for rescuing from all FccReboot errors
+  class Error < StandardError; end
+
+  # Raised when FccReboot returns a 400 HTTP status code
+  class BadRequest < Error; end
+
+  # Raised when FccReboot returns a 401 HTTP status code
+  class Unauthorized < Error; end
+
+  # Raised when FccReboot returns a 403 HTTP status code
+  class Forbidden < Error; end
+
+  # Raised when FccReboot returns a 404 HTTP status code
+  class NotFound < Error; end
+
+  # Raised when FccReboot returns a 406 HTTP status code
+  class NotAcceptable < Error; end
+
+  # Raised when FccReboot returns a 500 HTTP status code
+  class InternalServerError < Error; end
+
+  # Raised when FccReboot returns a 502 HTTP status code
+  class BadGateway < Error; end
+
+  # Raised when FccReboot returns a 503 HTTP status code
+  class ServiceUnavailable < Error; end
+end

data/lib/fcc_reboot/client.rb

@@ -0,0 +1,20 @@
+require ::File.expand_path('../client/connection', __FILE__)
+require ::File.expand_path('../client/request', __FILE__)
+require ::File.expand_path('../client/api.rb', __FILE__)
+
+module FccReboot
+  class Client
+    attr_accessor *Configuration::VALID_OPTIONS_KEYS
+
+    def initialize(options={})
+      options = FccReboot.options.merge(options)
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key])
+      end
+    end
+
+    include FccReboot::Client::Connection
+    include FccReboot::Client::Request
+    include FccReboot::Client::Api
+  end
+end

data/lib/fcc_reboot/client/api.rb

@@ -0,0 +1,233 @@
+# -*- coding: utf-8 -*-
+require 'JSON'
+
+module FccReboot
+  class Client
+    module Api
+      # speed test statistics for a US County given the passed Latitude and Longitude
+      #
+      # @format :json
+      # @key false
+      # @param options [Hash] A customizable set of options.
+      # @return [Array]
+      # @see http://reboot.fcc.gov/developer/consumer-broadband-test-api
+      # @example Provide speed test statistics for a US County given the passed Latitude and Longitude
+      #   FccReboot.broadband_test(:latitude => '38.0', :longitude => '-77.5')
+      def broadband_test(options={})
+        options.merge!({:format => "json"})                
+        response = get('speedtest/find', options)
+        JSON.parse(response)["SpeedTestCounty"]
+      end
+      
+      # This API returns the US Census Bureau Census Block number (aka the 15 character FIPS Code) given 
+      # a passed Latitude and Longitude. The API also returns the US State and County name associated with 
+      # the Block.
+      #
+      # @format :json
+      # @key false
+      # @param options [Hash] A customizable set of options.
+      # @return [Hash]
+      # @see http://reboot.fcc.gov/developer/census-block-conversions-api
+      # @example Provide census block info for the given latitude and longitude
+      #   FccReboot.find_census_block({:latitude => '38.0', :longitude => '-77.5'})
+      def find_census_block(options={})
+        options.merge!({:format => "json"})
+        response = get('block/find', options)
+        JSON.parse(response)
+      end
+
+      # This API returns returns all the broadband providers in a given state, where those operators
+      # or do not operate in multiple states.
+      #
+      # @format :json
+      # @key false
+      # @param options [Hash] A customizable set of options.
+      # @return [Hash]
+      # @see http://reboot.fcc.gov/developer/frn-conversions-api
+      # @example Provide FRN list for the state of Illinois
+      #   FccReboot.frn_getlist({:stateCode => 'IL', :multi => 'No'})
+      def frn_getlist(options={})
+        options[:multi] = options[:multi] ? "Yes" : "No"
+        options.merge!({:format => "json"})
+        response = get('frn/getList', options)
+        JSON.parse(response)
+      end
+      
+      # This API returns information about a provider by FRN number.
+      #
+      # @format :json
+      # @key false
+      # @param options [Hash] A customizable set of options.
+      # @return [Hash]
+      # @see http://reboot.fcc.gov/developer/frn-conversions-api
+      # @example Provide FRN info for Cygnus Telecommunications Corporation (FRN number 0017855545)
+      #   FccReboot.frn_getinfo(:frn => '0017855545')
+      def frn_getinfo(options={})
+        options.merge!({:format => "json"})
+        response = get('frn/getInfo', options)
+        JSON.parse(response)
+      end
+      
+      # This API accepts a frequency range and returns a list of the frequency bands 
+      # along with a high level description of how the band is allocated and for what uses within the 225 MHz and 3700 MHz frequency range.
+      # @format :json
+      # @key false
+      # @param options [Hash] A customizable set of options:
+      # frequencyFrom (Optional) – If a frequency range is not provided then the API will return all spectrum bands falling within the 225 to 3700 MHz range. Both a lower and upper frequency value must be provided when entering search criteria.
+      # frequencyTo (Optional) – If a frequency range is not provided then the API will return all spectrum bands falling within the 225 to 3700 MHz range. Both a lower and upper frequency value must be provided when entering search criteria.
+      # pageNum (Optional) – Default is 1.
+      # sortColumn (Optional) – Default is lowerBand. Valid values are: lowerBand, upperBand, or desc.
+      # sortOrder (Optional) – Default is asc. Valid values are: asc, desc.
+      # pageSize (Optional) – Default value is 1000.
+      # limit (Optional) – Default value is 100.
+      # format (Optional) – Default value is xml. Valid values are: xml, json, jsonp
+      # jsonCallback (Optional) – Default value is callback.
+      # @return [Array]
+      # @see http://reboot.fcc.gov/developer/spectrum-dashboard-api
+      # @example Returns a list of the frequency bands 
+      #   FccReboot.get_spectrum_bands(:frequencyFrom=>'226', :frequencyTo => '900')
+      def get_spectrum_bands(options={})
+        options.merge!({:format => "json"})          
+        response = get('spectrum-view/services/advancedSearch/getSpectrumBands', options)      
+        JSON.parse(response)["SpectrumBands"]["SpectrumBand"]        
+      end
+      
+      # This API returns a high level overview of who owns spectrum across the country 
+      # within the 225 MHz to 3700 MHz frequency range in radio services deemed appropriate for 
+      # mobile broadband use. 
+      # @format :json
+      # @key false
+      # @param options [Hash] A customizable set of options:
+      # frequencyFrom (Optional) – If a frequency range is not provided then the API will return all spectrum bands falling within the 225 to 3700 MHz range. Both a lower and upper frequency value must be provided when entering search criteria.
+      # frequencyTo (Optional) – If a frequency range is not provided then the API will return all spectrum bands falling within the 225 to 3700 MHz range. Both a lower and upper frequency value must be provided when entering search criteria.
+      # pageNum (Optional) – Default is 1.
+      # sortColumn (Optional) – Default is lowerBand. Valid values are: lowerBand, upperBand, or desc.
+      # sortOrder (Optional) – Default is asc. Valid values are: asc, desc.
+      # pageSize (Optional) – Default value is 1000.
+      # limit (Optional) – Default value is 100.
+      # format (Optional) – Default value is xml. Valid values are: xml, json, jsonp
+      # @return [Array]
+      # @see http://reboot.fcc.gov/developer/spectrum-dashboard-api
+      # @example Provide high level overview of who owns spectrum across the country within the 225 MHz to 3700 MHz frequency
+      #   FccReboot.get_license(:name=> 'AT', :radioservice=>'Cellular')
+      def get_spectrum_licenses(options={})
+        options.merge!({:format => "json"})
+        response = get('spectrum-view/services/advancedSearch/getLicenses', options)
+        JSON.parse(response)["Licenses"]["License"]        
+      end
+      
+      # his API returns high level license information including name, FRN, call sign, 
+      # category, service, status, expiration date and license id, based on the search criteria passed. 
+      # @format :json
+      # @key false
+      # @param options [Hash] A customizable set of options:
+      # searchValue (Required)
+      # pageNum (Optional) – Default is 1.
+      # sortColumn (Optional) – Default is licName. Valid values are: licName, frn, callsign, service, status, expdate
+      # sortOrder (Optional) – Default is asc. Valid values are: asc, desc
+      # pageSize (Optional) – Default is 100.
+      # @return [Array]
+      # @see http://reboot.fcc.gov/developer/license-view-api
+      # @example Provide number of licenses that were issued by the Commission on a yearly basis
+      #   FccReboot.get_licenses(:searchValue => 'Verizon Wireless')
+      def get_licenses(options={})
+        options.merge!({:format => "json"})        
+        response = get('license-view/basicSearch/getLicenses', options)
+        JSON.parse(response)["Licenses"]["License"]
+      end
+
+      # This API returns a list of currently known licensee names associated with a common name.
+      # @format :json
+      # @key false
+      # @param options [Hash] A customizable set of options:
+      # commonName (Optional)
+      # limit (Optional) – Number of request rows
+      # @return [Array]
+      # @see http://reboot.fcc.gov/developer/license-view-api
+      # @example Returns a list of currently known licensee names associated with a common name.
+      #   FccReboot.get_common_names(:commonName => 'Sprint Nextel')
+      def get_common_names(options={})
+        options.merge!({:format => "json"})        
+        response = get('license-view/licenses/getCommonNames', options)
+        JSON.parse(response)['Stats']['Stat']
+      end
+      
+      # This API returns the license counts and percent distribution by status.
+      # @format :json
+      # @key false
+      # @param options [Hash] A customizable set of options:
+      # commonName (Optional)
+      # limit (Optional) – Number of request rows
+      # @return [Array]
+      # @see http://reboot.fcc.gov/developer/license-view-api
+      # @example Returns the license counts and percent distribution by status.
+      #   FccReboot.get_statuses(:commonName => 'Sprint Nextel')
+      def get_statuses(options={})
+        options.merge!({:format => "json"})        
+        response = get('license-view/licenses/getStatuses', options)
+        JSON.parse(response)['Stats']['Stat']
+      end
+
+      # This API returns the number of licenses that were issued by the Commission on a yearly basis. 
+      #The data returned includes the year and the total number of licenses issued.
+      # @format :json
+      # @key false
+      # @param options [Hash] A customizable set of options:
+      # commonName - Name of the coporation
+      # @return [Array]
+      # @see http://reboot.fcc.gov/developer/license-view-api
+      # @example Provide number of licenses that were issued by the Commission on a yearly basis
+      #   FccReboot.get_issued(:commonName=> 'Sprint Nextel')
+      def get_issued(options={})
+        options.merge!({:format => "json"})
+        response = get('license-view/licenses/getIssued', options)
+        JSON.parse(response)["Stats"]["Stat"]
+      end
+      
+      # This API returns the number of licenses up for renewal in a given month. The API returns 12 months worth of data.
+       # @format :json
+       # @key false
+       # @param options [Hash] A customizable set of options:
+       # commonName - Name of the coporation
+       # @return [Array]
+       # @see http://reboot.fcc.gov/developer/license-view-api
+       # @example Returns the number of licenses up for renewal in a given month. The API returns 12 months worth of data for Sprint Nextel.
+       #   FccReboot.get_renewals(:commonName=> 'Sprint Nextel')
+       def get_renewals(options={})
+         options.merge!({:format => "json"})
+         response = get('license-view/licenses/getRenewals', options)
+         JSON.parse(response)["Stats"]["Stat"]
+       end
+       
+       # This API returns the counts and percent distribution of active licenses by entity type. 
+       # There are four entity categories: Individual, Business, Government and Other.
+        # @format :json
+        # @key false
+        # @param options [Hash] A customizable set of options:
+        # @return [Array]
+        # @see http://reboot.fcc.gov/developer/license-view-api
+        # @example Returns the counts and percent distribution of active licenses by entity type
+        #   FccReboot.get_renewals()
+        def get_entities(options={})
+          options.merge!({:format => "json"})
+          response = get('license-view/licenses/getEntities', options)
+          JSON.parse(response)["Stats"]["Stat"]
+        end
+        
+        # This API returns the counts and percent distribution of active licenses by category. A license falls into only one category.
+         # There are four entity categories: Individual, Business, Government and Other.
+          # @format :json
+          # @key false
+          # @param options [Hash] A customizable set of options:
+          # @return [Array]
+          # @see http://reboot.fcc.gov/developer/license-view-api
+          # @example Returns the counts and percent distribution of active licenses by category
+          #   FccReboot.get_categories()
+          def get_categories(options={})
+            options.merge!({:format => "json"})
+            response = get('license-view/licenses/getCategories', options)
+            JSON.parse(response)["Stats"]["Stat"]
+          end
+    end
+  end
+end