urban-mapping-api 0.9.3

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Michael Dwan
+
+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.rdoc

@@ -0,0 +1,82 @@
+= urban-mapping-api
+
+A simple ruby interface to Urban Mapping's free and premium neighborhood lookup API.
+
+== Installation
+
+  sudo gem install michaeldwan-urban-mapping-api
+  
+Gem dependencies:
+
+* curb
+* json
+
+== Examples
+
+To get started you need to require 'urban-mapping-api':
+
+  % irb -rubygems
+  irb(main):001:0> require 'urban-mapping-api'
+  # => true
+
+Before you do anything, create an instance of UrbanMapping::Interface
+
+  interface = UrbanMapping::Interface.new('my-api-key')
+  
+For premium API access, include the premium API key
+
+  interface = UrbanMapping::Interface.new('my-api-key', :shared_secret => 'my-shared-secred')
+  interface.premium_api? 
+  # => true
+  
+The default return value of all methods is an OpenStruct or array of OpenStructs.
+
+  interface = UrbanMapping::Interface.new('my-api-key')
+  hood = interface.get_neighborhood_detail(3094847)
+  hood
+  # => #<OpenStruct city="Chicago", name="The Loop", state="IL", ...>
+  hood.city
+  # => "Chicago"
+
+If you want the raw hash output, pass :raw => true to the constructor
+
+  interface = UrbanMapping::Interface.new('my-api-key', :shared_secret => 'my-shared-secred', :raw => true)
+  hood = interface.get_neighborhood_detail(3094847)
+  hood
+  # => {"wkt_centroid"=>"POINT(-87.6260772332496 41.8782770670931)", "name"=>"The Loop", "city"=>"Chicago"...
+  hood.city
+  # => "Chicago"
+
+(If you don't have an api key, go get one at http://developer.urbanmapping.com/accounts/register/)
+
+Now that you have an instance of the interface, you can make calls to the service. (The below examples are using raw output.)
+
+  interface.get_neighborhoods_by_postal_code('60654')
+  # => [{"name"=>"River North", "city"=>"Chicago", "country"=>"USA", "id"=>3320072, "state"=>"IL"}, ...]
+  
+  interface.get_neighborhoods_by_lat_lng(41.882088, -87.624454)
+  # => [{"name"=>"The Loop", "city"=>"Chicago", "country"=>"USA", "id"=>3094847, "state"=>"IL"}]
+
+  interface.get_neighborhood_detail(3094847)
+  # => {"wkt_centroid"=>"POINT(-87.6260772332496 41.8782770670931)", "name"=>"The Loop", "city"=>"Chicago"...
+  
+== Helpful Links
+
+* urban-mapping-api Gem documentation http://rdoc.info/projects/michaeldwan/urban-mapping-api
+* Urban Mapping http://www.urbanmapping.com/urbanware/neighborhood-database/index.html
+* Api Documentation http://developer.urbanmapping.com/docs/neighborhoods
+* Register for a free API key http://developer.urbanmapping.com/accounts/register
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2009 Michael Dwan. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,56 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "urban-mapping-api"
+    gem.summary = "A simple ruby interface to Urban Mapping's free and premium neighborhood lookup API"
+    gem.description = "A simple ruby interface to Urban Mapping's free and premium neighborhood lookup API"
+    gem.email = "mpdwan@gmail.com"
+    gem.homepage = "http://github.com/michaeldwan/urban-mapping-api"
+    gem.authors = ["Michael Dwan"]
+    gem.add_development_dependency "thoughtbot-shoulda"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION')
+    version = File.read('VERSION')
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "urban-mapping-api #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.9.3

data/lib/core_ext.rb

@@ -0,0 +1,39 @@
+class Object
+  def to_openstruct
+    self
+  end
+
+  module InstanceExecHelper; end
+  
+  include InstanceExecHelper
+  def instance_exec(*args, &block)
+    begin
+      old_critical, Thread.critical = Thread.critical, true
+      n = 0
+      n += 1 while respond_to?(mname="__instance_exec#{n}")
+      InstanceExecHelper.module_eval{ define_method(mname, &block) }
+    ensure
+      Thread.critical = old_critical
+    end
+    begin
+      ret = send(mname, *args)
+    ensure
+      InstanceExecHelper.module_eval{ remove_method(mname) } rescue nil
+    end
+    ret
+  end
+end
+
+class Array
+  def to_openstruct
+    map{ |el| el.to_openstruct }
+  end
+end
+
+class Hash
+  def to_openstruct
+    mapped = {}
+    each{ |key,value| mapped[key] = value.to_openstruct }
+    UrbanMapping::NeighborhoodOpenStruct.new(mapped)
+  end
+end

data/lib/urban-mapping-api.rb

@@ -0,0 +1,136 @@
+require 'curl'
+require 'json'
+require 'digest'
+require 'ostruct'
+require 'uri'
+require "#{File.dirname(__FILE__)}/core_ext"
+
+module UrbanMapping
+  class RequestError < StandardError
+    attr_reader :code, :url, :message
+    def initialize(code, url, message)
+      @code = code
+      @url = url
+      @message = message
+    end
+  end
+  
+  class NeighborhoodOpenStruct < OpenStruct
+    def id
+      @table[:id] || super
+    end
+  end
+  
+  class Interface
+    ENDPOINT = 'http://api1.urbanmapping.com/neighborhoods/rest'
+
+    attr_reader :api_key, :shared_secret, :options3
+    
+    # Create a new instance.
+    # Requeres an api_key. A shared key needs to be provided for 
+    # access to premium API methods.
+    def initialize(api_key, options = {})
+      options = {
+        :raw => false
+      }.merge(options)
+      @api_key = api_key
+      @shared_secret = options.delete(:shared_secret)
+      @options = options
+    end
+    
+    # Returns true if a shard_secret was provided to the constructor.
+    def premium_api?
+      !shared_secret.nil?
+    end
+    
+    # Returns a list of neighborhoods whose boundaries contain the requested 
+    # latitude and longitude.
+    def get_neighborhoods_by_lat_lng(latitude, longitude)
+      perform('getNeighborhoodsByLatLng', :lat => latitude, :lng => longitude)
+    end
+
+    # Returns the neighborhood whose centroid is nearest to the requested 
+    # latitude and longitude within a 20 linear mile range.
+    def get_nearest_neighborhood(latitude, longitude)
+      perform('getNearestNeighborhood', :lat => latitude, :lng => longitude)
+    end
+    
+    # Returns a list of neighborhoods within a bounding box extent defined by 
+    # southwestern and northeastern corners. Note query extents covering more 
+    # than 45 square miles will be rejected.
+    def get_neighborhoods_by_extent(southwest_latitude, southwest_longitude, northeast_latitude, northeast_longitude)
+      perform('getNeighborhoodsByExtent', :swlat => southwest_latitude, 
+                                          :swlng => southwest_longitude,
+                                          :nelat => northeast_latitude,
+                                          :nelng => northeast_longitude)
+    end
+
+    # This method first geocodes the input address, then returns the geocode 
+    # and lists neighborhoods containing the point in a single response. 
+    # This is technically executed in a single request, but for the purposes 
+    # of account administration a single invocation is counted as two calls.
+    def get_neighborhoods_by_address(street, city, state, country = 'USA')
+      perform('getNeighborhoodsByAddress', :street => street,
+                                           :city => city,
+                                           :state => state,
+                                           :country => country)
+    end
+    
+    # Returns a list of neighborhood for the requested city.
+    def get_neighborhoods_by_city_state_country(city, state, country = 'USA')
+      perform('getNeighborhoodsByCityStateCountry', :city => city,
+                                                    :state => state,
+                                                    :country => country)
+    end
+
+    # Returns a list of neighborhoods whose areas intersect that of the requested postal code.
+    def get_neighborhoods_by_postal_code(postal_code)
+      perform('getNeighborhoodsByPostalCode', :postalCode => postal_code)
+    end
+    
+    # Returns a list of neighborhoods for the requested neighborhood name.
+    def get_neighborhoods_by_name(name)
+      perform('getNeighborhoodsByName', :name => name)
+    end
+    
+    # Returns neighborhood details for the requested neighborhood ID.
+    def get_neighborhood_detail(id)
+      perform('getNeighborhoodDetail', :neighborhoodId => id)
+    end
+    
+    # Returns neighborhood relationship attributes for the requested neighborhood ID.
+    def get_neighborhood_relationships(id)
+      perform('getNeighborhoodRelationships', :neighborhoodId => id)
+    end
+
+    private
+      def generate_signature
+        Digest::MD5.hexdigest([api_key, shared_secret, Time.now.utc.to_i.to_s].join)
+      end
+
+      def perform(method, parameters)
+        parameters.merge!({
+          :format => 'json',
+          :apikey => api_key
+        })
+        parameters.merge!(:sig => generate_signature) if premium_api?
+        
+        query_string = parameters.to_a.map{ |x| x.map{|val| URI.encode(val.to_s)}.join('=') }.join('&')
+
+        url = "#{ENDPOINT}/#{method}?#{query_string}"
+        response = Curl::Easy.perform(url)
+
+        if response.response_code != 200
+          raise RequestError.new(response.response_code, url, response.body_str)
+        end
+        
+        output = JSON.parse(response.body_str)
+        
+        return output if options[:raw]
+
+        output.to_openstruct
+      rescue StandardError => ex
+        raise "An error occured while calling #{url}: #{ex.message}\n#{ex.backtrace}"
+      end
+  end  
+end

data/test/test_helper.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'urban-mapping-api'
+
+class Test::Unit::TestCase
+end

data/test/urban-mapping-api_test.rb

@@ -0,0 +1,7 @@
+require 'test_helper'
+
+class UrbanMappingApiTest < Test::Unit::TestCase
+  should "probably rename this file and start testing for real" do
+    flunk "hey buddy, you should probably rename this file and start testing for real"
+  end
+end

data/urban-mapping-api.gemspec

@@ -0,0 +1,55 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{urban-mapping-api}
+  s.version = "0.9.3"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Michael Dwan"]
+  s.date = %q{2009-12-02}
+  s.description = %q{A simple ruby interface to Urban Mapping's free and premium neighborhood lookup API}
+  s.email = %q{mpdwan@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "lib/core_ext.rb",
+     "lib/urban-mapping-api.rb",
+     "test/test_helper.rb",
+     "test/urban-mapping-api_test.rb",
+     "urban-mapping-api.gemspec"
+  ]
+  s.homepage = %q{http://github.com/michaeldwan/urban-mapping-api}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{A simple ruby interface to Urban Mapping's free and premium neighborhood lookup API}
+  s.test_files = [
+    "test/test_helper.rb",
+     "test/urban-mapping-api_test.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+    else
+      s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+  end
+end
+

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification 
+name: urban-mapping-api
+version: !ruby/object:Gem::Version 
+  version: 0.9.3
+platform: ruby
+authors: 
+- Michael Dwan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-12-02 00:00:00 -06:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: thoughtbot-shoulda
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: A simple ruby interface to Urban Mapping's free and premium neighborhood lookup API
+email: mpdwan@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/core_ext.rb
+- lib/urban-mapping-api.rb
+- test/test_helper.rb
+- test/urban-mapping-api_test.rb
+- urban-mapping-api.gemspec
+has_rdoc: true
+homepage: http://github.com/michaeldwan/urban-mapping-api
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: A simple ruby interface to Urban Mapping's free and premium neighborhood lookup API
+test_files: 
+- test/test_helper.rb
+- test/urban-mapping-api_test.rb