broadband_map 0.0.1

data/lib/broadband_map/client/census.rb

@@ -0,0 +1,46 @@
+module BroadbandMap
+  class Client
+    module Census
+      
+      # Returns the US Census Block geography ID information given a passed Latitude and Longitude.
+      # @param params [Hash] :geography_type, :latitude, :longitude and optional :format, :callback
+      # @param options [Hash] A customizable set of options. 
+      # @return {Hash}
+      # @see http://www.broadbandmap.gov/developer/api/census-api-by-coordinates
+      # @example
+      #   census_coords({:geography_type => 'block', :latitude => 42.456, :longitude => 74.987})
+      
+      def census_coords(params={}, options={})
+        params = {:format => 'json'}.merge(params)
+        get("census/#{params[:geography_type]}?latitude=#{params[:latitude]}&longitude=#{params[:longitude]}&format=#{params[:format]}&callback=#{params[:callback]}")
+      end
+      
+      # Returns the geography of a specified geography type by geography id within the entire United States.
+      # @param params [Hash] :geography_type, :fips and optional :format, :callback
+      # @param options [Hash] A customizable set of options. 
+      # @return {Hash}
+      # @see http://www.broadbandmap.gov/developer/api/census-api-by-fips-code
+      # @example
+      #   census_fips({:geography_type => 'state', :fips => '36'})
+      
+      def census_fips(params={}, options={})
+        params = {:format => 'json'}.merge(params)
+        get("census/#{params[:geography_type]}/fips/#{params[:fips]}?format=#{params[:format]}&callback=#{params[:callback]}")
+      end
+      
+      # Returns all the geographies specified by a geography name (e.g., Washington) of a specific geography type (e.g., congressional district) within the entire United States.
+      # @param params [Hash] :geography_type, :geography_name and optional :format, :max_results, :callback
+      # @param options [Hash] A customizable set of options. 
+      # @return {Hash}
+      # @see http://www.broadbandmap.gov/developer/api/census-api-by-geography-name
+      # @example
+      #   census_geo_name({:geography_type => 'county', :geography_name => 'fai'})
+      
+      def census_geo_name(params={}, options={})
+        params = {:format => 'json', :max_results => 100}.merge(params)
+        get("census/#{params[:geography_type]}/#{params[:geography_name]}?format=#{params[:format]}&maxresults=#{params[:max_results]}&all=#{params[:all]}")
+      end
+      
+    end
+  end
+end

data/lib/broadband_map/client/connection.rb

@@ -0,0 +1,19 @@
+require 'faraday_middleware'
+
+module BroadbandMap
+  class Client
+    module Connection
+      private
+
+      def connection
+        Faraday.new(:url => 'http://www.broadbandmap.gov/broadbandmap/') do |connection|
+          connection.use Faraday::Request::UrlEncoded
+          connection.use Faraday::Response::RaiseError
+          connection.use Faraday::Response::Rashify
+          connection.use Faraday::Response::ParseJson
+          connection.adapter(Faraday.default_adapter)
+        end
+      end
+    end
+  end
+end

data/lib/broadband_map/client/demographics.rb

@@ -0,0 +1,65 @@
+module BroadbandMap
+  class Client
+    module Demographics
+      
+      # Returns the demographics data from the coordinates.
+      # @param params [Hash] :data_version, :latitude, :longitude and optional :format, :callback
+      # @param options [Hash] A customizable set of options. 
+      # @return {Hash}
+      # @see http://www.broadbandmap.gov/developer/api/demographics-api-by-coordinates
+      # @example
+      #   demographics_coords({:data_version => 'fall2010', :latitude => 42.456, :longitude => -74.987})
+      
+      def demographics_coords(params={}, options={})
+        params = {:format => 'json'}.merge(params)
+        get("demographic/#{params[:data_version]}/coordinates?latitude=#{params[:latitude]}&longitude=#{params[:longitude]}&format=#{params[:format]}&callback=#{params[:callback]}")
+      end
+   
+      # Returns the demographic information for a particular geography type and geography ID
+      # @param params [Hash] :data_version, :geography_type, :geography_ids and optional :format, :callback
+      # @param options [Hash] A customizable set of options. 
+      # @return {Hash}
+      # @see http://www.broadbandmap.gov/developer/api/demographics-api-by-geography-type-and-geography-id
+      # @example
+      #   demographics_geo_id({:data_version => 'fall2010', :geography_type => 'county', :geography_ids => ['17081', '17083']})
+   
+      def demographics_geo_id(params={}, options={})
+        params = {:format => 'json'}.merge(params)
+        ids = ""
+        params[:geography_ids].each {|x| ids += x +","}
+        ids.chop!
+        get("demographic/#{params[:data_version]}/#{params[:geography_type]}/ids/#{ids}?format=#{params[:format]}&callback=#{params[:callback]}")
+      end
+      
+      # Returns the demographic information for a particular geography type and geography name.
+      # @param params [Hash] :data_version, :geography_type, :geography_names and optional :format, :callback
+      # @param options [Hash] A customizable set of options. 
+      # @return {Hash}
+      # @see http://www.broadbandmap.gov/developer/api/demographics-api-by-geography-type-and-geography-name
+      # @example
+      #   demographics_geo_name({:data_version => 'fall2010', :geography_type => 'county', :geography_names => ['jersey', 'jefferson']})
+      
+      def demographics_geo_name(params={}, options={})
+        params = {:format => 'json'}.merge(params)
+        names = ""
+        params[:geography_names].each {|x| names += x +","}
+        names.chop!
+        get("demographic/#{params[:data_version]}/#{params[:geography_type]}/names/#{names}?format=#{params[:format]}&callback=#{params[:callback]}")
+      end
+      
+      # Returns the demographic information for the whole nation.
+      # @param params [Hash] :data_version, and optional :format, :callback
+      # @param options [Hash] A customizable set of options. 
+      # @return {Hash}
+      # @see http://www.broadbandmap.gov/developer/api/demographics-api-nation
+      # @example
+      #   demographics_nation({:data_version => 'fall2010'})
+      
+      def demographics_nation(params={}, options={})
+        params = {:format => 'json'}.merge(params)
+        get("demographic/#{params[:data_version]}/nation?format=#{params[:format]}&callback=#{params[:callback]}")
+      end
+      
+    end
+  end
+end

data/lib/broadband_map/client/geography.rb

@@ -0,0 +1,72 @@
+module BroadbandMap
+  class Client
+    module Geography
+      
+      # Returns a geography of a specified geography type by the geography id.
+      # @param params [Hash]  :geography_type, :geography_id and optional :format, :callback
+      # @param options [Hash] A customizable set of options. 
+      # @return {Hash}
+      # @see http://www.broadbandmap.gov/developer/api/geography-lookup-api-by-geography-id
+      # @example
+      #   geography_id({:geography_type => 'congdistrict', :geography_id => '0111101'})
+      
+      def geography_id(params={}, options={})
+        params = {:format => 'json'}.merge(params)
+        get("geography/#{params[:geography_type]}/id/#{params[:geography_id]}?format=#{params[:format]}&callback=#{params[:callback]}")
+      end
+      
+      # Returns all geographies of a specified geography type.
+      # @param params [Hash]  :geography_type, and optional :format, :max_results, :callback
+      # @param options [Hash] A customizable set of options. 
+      # @return {Hash}
+      # @see http://www.broadbandmap.gov/developer/api/geography-lookup-api-by-geography-type
+      # @example
+      #   geography_type({:geography_type => 'congdistrict', :max_results => 1000})
+      
+      def geography_type(params={}, options={})
+        params = {:format => 'json', :max_results => 100}.merge(params)
+        get("geography/#{params[:geography_type]}?format=#{params[:format]}&maxresults=#{params[:max_results]}&all=#{params[:all]}&callback=#{params[:callback]}")
+      end
+      
+      # Returns geographies by name of a specific geography type.
+      # @param params [Hash]  :geography_type, :geography_name and optional :format, :max_results, :callback
+      # @param options [Hash] A customizable set of options. 
+      # @return {Hash}
+      # @see http://www.broadbandmap.gov/developer/api/geography-lookup-api-by-geography-type-and-geography-name
+      # @example
+      #   geography_type_name({:geography_type => 'censusplace', :geography_name => 'sei'})
+      
+      def geography_type_name(params={}, options={})
+        params = {:format => 'json', :max_results => 100}.merge(params)
+        get("geography/#{params[:geography_type]}/name/#{params[:geography_name]}?format=#{params[:format]}&maxresults=#{params[:max_results]}&all=#{params[:all]}&callback=#{params[:callback]}")
+      end
+      
+      # Returns all geographies of specific geography type within a state.
+      # @param params [Hash]  :state_fips, :geography_type, :geography_type and optional :format, :max_results, :callback
+      # @param options [Hash] A customizable set of options. 
+      # @return {Hash}
+      # @see http://www.broadbandmap.gov/developer/api/geography-lookup-api-by-geography-type-within-a-state
+      # @example
+      #   geography_type_state({:geography_type => 'msa', :state_fips => '01'})
+      
+      def geography_type_state(params={}, options={})
+        params = {:format => 'json', :max_results => 100}.merge(params)
+        get("geography/state/#{params[:state_fips]}/#{params[:geography_type]}?format=#{params[:format]}&maxresults=#{params[:max_results]}&all=#{params[:all]}&callback=#{params[:callback]}")
+      end
+      
+      # Returns geographies by name of a specific geography type within a state.
+      # @param params [Hash]  :state_fips, :geography_type, :geography_name and optional :format, :max_results, :callback
+      # @param options [Hash] A customizable set of options. 
+      # @return {Hash}
+      # @see http://www.broadbandmap.gov/developer/api/geography-lookup-api-by-name-of-specific-geography-type-within-a-state
+      # @example
+      #   geography_type_name_state({:geography_type => 'county', :state_fips => '17', :geography_name => 'mar'})
+      
+      def geography_type_name_state(params={}, options={})
+        params = {:format => 'json', :max_results => 100}.merge(params)
+        get("geography/state/#{params[:state_fips]}/#{params[:geography_type]}/name/#{params[:geography_name]}?format=#{params[:format]}&maxresults=#{params[:max_results]}&all=#{params[:all]}&callback=#{params[:callback]}")
+      end
+      
+    end
+  end
+end

data/lib/broadband_map/client/provider.rb

@@ -0,0 +1,34 @@
+module BroadbandMap
+  class Client
+    module Provider
+      
+      # Returns all providers.
+      #
+      # @param params [Hash] options for the lookup.
+      # @param options [Hash] A customizable set of options. 
+      # @return {Hash}
+      # @see http://www.broadbandmap.gov/developer/api/broadband-provider-api-all-providers
+      # @example
+      #   provider_all()
+      
+      def provider_all(params={}, options={})
+        params = {:format => 'json'}.merge(params)
+        get("provider?format=#{params[:format]}&callback=#{params[:callback]}")
+      end
+      
+      # Searches for all providers with a specified name.
+      #
+      # @param params [Hash] options for the lookup.
+      # @param options [Hash] A customizable set of options. 
+      # @return {Hash}
+      # @see http://www.broadbandmap.gov/developer/api/broadband-provider-api-by-provider-names
+      # @example
+      #   provider_name({:name => 'alb'})
+      
+      def provider_name(params={}, options={})
+        params = {:format => 'json', :max_results => 20}.merge(params)
+        get("provider/name/#{params[:name]}?format=#{params[:format]}&all=#{params[:all]}&maxresults=#{params[:max_results]}&callback=#{params[:callback]}")
+      end
+    end
+  end
+end

data/lib/broadband_map/client/request.rb

@@ -0,0 +1,18 @@
+module BroadbandMap
+  class Client
+    module Request
+      def get(path, options={})
+        request(:get, path, options)
+      end
+
+      private
+
+      def request(method, path, options)
+        response = connection.send(method) do |request|
+          request.url(path, options)
+        end
+        response.body
+      end
+    end
+  end
+end

data/lib/broadband_map/client/speed_test.rb

@@ -0,0 +1,65 @@
+module BroadbandMap
+  class Client
+    module SpeedTest
+      
+      # Returns the speed test results for a particular geography type (e.g., state, congressional district) and geography ID.
+      # @param params [Hash] :geogrpahy_type and :geography_ids and optional :speed_test_type, :format, :callback
+      # @param options [Hash] A customizable set of options. 
+      # @return {Hash}
+      # @see http://www.broadbandmap.gov/developer/api/speed-test-api-by-geography-type-and-geography-id
+      # @example
+      #   speed_test_geo_type_id({:geography_type => 'state', :geography_ids => ['01', '02']})
+      
+      def speed_test_geo_type_id(params={}, options={})
+        params = {:format => 'json'}.merge(params)
+        ids = ""
+        params[:geography_ids].each {|x| ids += x +","}
+        ids.chop!
+        get("speedtest/#{params[:geography_type]}/ids/#{ids}?format=#{params[:format]}&speedtesttype=#{params[:speed_test_type]}&callback=#{params[:callback]}")
+      end
+      
+      # Returns the speed test results for a particular geography type (e.g., state, congressional district) and geography name (e.g., Virginia).
+      # @param params [Hash] :geogrpahy_type and :geography_names and optional :speed_test_type, :format, :callback
+      # @param options [Hash] A customizable set of options. 
+      # @return {Hash}
+      # @see http://www.broadbandmap.gov/developer/api/speed-test-api-by-geography-type-and-geography-name
+      # @example
+      #   speed_test_geo_type_name({:geography_type => 'state', :geography_names => ['alabama', 'arizona']})
+      
+      def speed_test_geo_type_name(params={}, options={})
+        params = {:format => 'json'}.merge(params)
+        names = ""
+        params[:geography_names].each {|x| names += x +","}
+        names.chop!
+        get("speedtest/#{params[:geography_type]}/names/#{names}?format=#{params[:format]}&speedtesttype=#{params[:speed_test_type]}&callback=#{params[:callback]}")
+      end
+      
+      # Returns the minimum and maximum quartile speeds by geography type within the nation.
+      # @param params [Hash] :geogrpahy_type and optional :speed_test_type, :format, :callback
+      # @param options [Hash] A customizable set of options. 
+      # @return {Hash}
+      # @see http://www.broadbandmap.gov/developer/api/speed-test-api-minimum-and-maximum-quartile-speeds-by-geography-type
+      # @example
+      #   speed_test_quartile({:geography_type => 'state'})
+      
+      def speed_test_quartile(params={}, options={})
+        params = {:format => 'json'}.merge(params)
+        get("speedtest/#{params[:geography_type]}/quartile?format=#{params[:format]}&speedtesttype=#{params[:speed_test_type]}&callback=#{params[:callback]}")
+      end   
+      
+      # Returns all the speed test results for the entire United States.
+      # @param params [Hash] optional :speed_test_type, :format, :callback
+      # @param options [Hash] A customizable set of options. 
+      # @return {Hash}
+      # @see http://www.broadbandmap.gov/developer/api/speed-test-api-nation
+      # @example
+      #   speed_test_nation()
+      
+      def speed_test_nation(params={}, options={})
+        params = {:format => 'json'}.merge(params)
+        get("speedtest/nation?format=#{params[:format]}&speedtesttype=#{params[:speed_test_type]}&callback=#{params[:callback]}")
+      end   
+      
+    end
+  end
+end

data/lib/broadband_map/client/summary.rb

@@ -0,0 +1,38 @@
+module BroadbandMap
+  class Client
+    module Summary
+
+      # Returns broadband summary data by geography IDs for a specific geography type
+      #
+      # @param params [Hash] :data_version, :census_metric_type, :geography_type (optional :format, :callback)
+      # @param options [Hash] A customizable set of options. 
+      # @return {Hash}
+      # @see http://www.broadbandmap.gov/developer/api/broadband-summary-api-by-geography-type-and-geography-id
+      # @example
+      #   summary_geo({:data_version => 'fall2010', :census_metric_type => 'population', :geography_type => 'state', :geography_ids => ['10']})
+
+      def summary_geo(params={}, options={})
+        params = {:format => 'json'}.merge(params)
+        ids = ""
+        params[:geography_ids].each {|x| ids += x +","}
+        ids.chop!
+        get("analyze/#{params[:data_version]}/summary/#{params[:census_metric_type]}/#{params[:geography_type]}/ids/#{ids}?format=#{params[:format]}&callback=#{params[:callback]}")
+      end
+      
+      # Returns broadband summary data for the nation
+      #
+      # @param params [Hash] :data_version, :census_metric_type (optional :format, :callback)
+      # @param options [Hash] A customizable set of options. 
+      # @return {Hash}
+      # @see http://www.broadbandmap.gov/developer/api/broadband-summary-api-nation
+      # @example
+      #   summary_nation(:data_version => 'fall2010', :census_metric_type => 'population')
+      
+      def summary_nation(params={}, options={})
+        params = {:format => 'json'}.merge(params)
+        get("analyze/#{params[:data_version]}/summary/#{params[:census_metric_type]}/nation?format=#{params[:format]}&callback=#{params[:callback]}")
+      end
+      
+    end
+  end
+end  

data/lib/broadband_map/client/wire.rb

@@ -0,0 +1,33 @@
+module BroadbandMap
+  class Client
+    module Wire
+      
+      # Returns all the wireless providers within a US census block given a passed latitude and longitude.
+      # @param params [Hash] :data_version, :latitude, :longitude and optional :max_results, :format, :callback
+      # @param options [Hash] A customizable set of options. 
+      # @return {Hash}
+      # @see http://www.broadbandmap.gov/developer/api/wireless-broadband-api
+      # @example
+      #   wireless({:data_version => 'fall2010', :latitude => 42.456, :longitude => -74.987})
+      
+      def wireless(params={}, options={})
+        params = {:format => 'json', :max_results => 100}.merge(params)
+        get("broadband/#{params[:data_version]}/wireless?latitude=#{params[:latitude]}&longitude=#{params[:longitude]}&format=#{params[:format]}&maxresults=#{params[:max_results]}&callback=#{params[:callback]}")
+      end
+      
+      # Returns  all the wireline providers within a US census block given a passed latitude and longitude.
+      # @param params [Hash] :data_version, :latitude, :longitude and optional :max_results, :format, :callback
+      # @param options [Hash] A customizable set of options. 
+      # @return {Hash}
+      # @see http://www.broadbandmap.gov/developer/api/wireline-broadband-api
+      # @example
+      #   wireline({:data_version => 'fall2010', :latitude => 42.456, :longitude => -74.987})
+      
+      def wireline(params={}, options={})
+        params = {:format => 'json', :max_results => 100}.merge(params)
+        get("broadband/#{params[:data_version]}/wireline?latitude=#{params[:latitude]}&longitude=#{params[:longitude]}&format=#{params[:format]}&maxresults=#{params[:max_results]}&callback=#{params[:callback]}")
+      end
+      
+    end
+  end
+end

data/lib/broadband_map/version.rb

@@ -0,0 +1,3 @@
+module BroadbandMap
+  VERSION = "0.0.1"
+end

data/spec/broadband_map/almanac_spec.rb

@@ -0,0 +1,74 @@
+require 'helper'
+
+describe BroadbandMap::Client::Almanac do
+
+  before do
+    @client = BroadbandMap::Client.new
+  end
+
+  describe ".almanac_parameters" do
+    before do
+      stub_get("almanac/parameters?format=json&callback=").
+        to_return(:status => 200, :body => fixture("almanac_parameters.json"))
+    end
+    
+    it "should return the correct item" do
+      test = @client.almanac_parameters()
+      a_get("almanac/parameters?format=json&callback=").should have_been_made
+      test.results.geographies.property[0].should == "tribalnation"
+    end
+  end
+  
+  describe ".almanac_ranking_geo_id_within_state" do
+    before do
+      stub_get("almanac/fall2010/rankby/state/01/population/wirelineproviderequals0/county/id/01101?format=json&order=asc&properties=&callback=").
+        to_return(:status => 200, :body => fixture("almanac_rank_geography_id_state.json"))
+    end
+    
+    it "should return the correct item" do
+      test = @client.almanac_ranking_geo_id_within_state({:data_version => 'fall2010', :state_id => '01', :census_metric_type => 'population', :ranking_metric => 'wirelineproviderequals0', :geography_type => 'county', :geography_id => '01101', :sort_order => 'asc'})
+      a_get("almanac/fall2010/rankby/state/01/population/wirelineproviderequals0/county/id/01101?format=json&order=asc&properties=&callback=").should have_been_made
+      test.results.all[0].rank.should == 1
+    end
+  end
+  
+  describe ".almanac_ranking_geo_id_within_nation" do
+    before do
+      stub_get("almanac/fall2010/rankby/nation/population/wirelineproviderequals0/county/id/51117?format=json&order=asc&properties=&callback=").
+        to_return(:status => 200, :body => fixture("almanac_rank_geography_id_nation.json"))
+    end
+    
+    it "should return the correct item" do
+      test = @client.almanac_ranking_geo_id_within_nation({:data_version => 'fall2010', :census_metric_type => 'population', :ranking_metric => 'wirelineproviderequals0', :geography_type => 'county', :geography_id => '51117', :sort_order => 'asc'})
+      a_get("almanac/fall2010/rankby/nation/population/wirelineproviderequals0/county/id/51117?format=json&order=asc&properties=&callback=").should have_been_made
+      test.results.firstTen[0].geographyId.should == "60020"
+    end
+  end
+  
+  describe ".almanac_ranking_geo_type_within_state" do
+    before do
+      stub_get("almanac/fall2010/rankby/state/01/population/wirelineproviderequals0/county?format=json&order=asc&properties=&callback=").
+        to_return(:status => 200, :body => fixture("almanac_rank_geo_type_state.json"))
+    end
+    
+    it "should return the correct item" do
+      test = @client.almanac_ranking_geo_type_within_state({:data_version => 'fall2010', :state_id => '01', :census_metric_type => 'population', :ranking_metric => 'wirelineproviderequals0', :geography_type => 'county', :sort_order => 'asc'})
+      a_get("almanac/fall2010/rankby/state/01/population/wirelineproviderequals0/county?format=json&order=asc&properties=&callback=").should have_been_made
+      test.results.all[0].geographyId.should == "01063"
+    end
+  end
+  
+  describe ".almanac_ranking_geo_type_within_nation" do
+    before do
+      stub_get("almanac/fall2010/rankby/nation/population/wirelineproviderequals0/county?format=json&order=asc&properties=&callback=").
+        to_return(:status => 200, :body => fixture("almanac_rank_geo_type_nation.json"))
+    end
+    
+    it "should return the correct item" do
+      test = @client.almanac_ranking_geo_type_within_nation({:data_version => 'fall2010', :census_metric_type => 'population', :ranking_metric => 'wirelineproviderequals0', :geography_type => 'county', :sort_order => 'asc'})
+      a_get("almanac/fall2010/rankby/nation/population/wirelineproviderequals0/county?format=json&order=asc&properties=&callback=").should have_been_made
+      test.results.firstTen[0].geographyId.should == "60020"
+    end
+  end
+
+end