guidestar-ruby 1.0.0

data/.gitignore

@@ -0,0 +1,6 @@
+.DS_Store
+*.log
+pkg/*
+coverage/*
+doc/*
+benchmarks/*

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/Gemfile.lock

@@ -0,0 +1,20 @@
+PATH
+  remote: .
+  specs:
+    guidestar-ruby (1.0.0)
+      nokogiri (~> 1.4.3.1)
+      rest-client (~> 1.6.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    mime-types (1.18)
+    nokogiri (1.4.3.1)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  guidestar-ruby!

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Gemini SBS, LLC
+
+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,142 @@
+# Guidestar
+
+Ruby wrapper around the [Guidestar](http://guidestar.org) API.
+
+## Install
+
+  gem install guidestar-ruby
+
+## Usage
+
+First initialize the client with your credentials:
+
+```ruby
+  Guidestar::Client.set_credentials(<user>, <password>)
+```
+
+Now you can perform searches by keyword:
+
+```ruby
+  Guidestar::Client.search(:keyword => "poverty")
+```
+
+Search by organization name:
+
+```ruby
+  Guidestar::Client.search(:name=> "Red Cross")
+```
+
+Search by EIN:
+
+```ruby
+  Guidestar::Client.search(:ein => "52-5367724")
+```
+
+Search by city and state:
+
+```ruby
+  Guidestar::Client.search(:city => "San Francisco", :state => "CA")
+```
+
+Search by zip:
+
+```ruby
+  Guidestar::Client.search(:zip => "23556")
+```
+
+Search by NTEE code:
+
+```ruby
+  Guidestar::Client.search(:ntee_code => "A25")
+```
+
+Additional options (and their respective defaults):
+
+```ruby
+  {
+    :page_size => 25, # number of results per page
+    :offset => 0,     # page number
+    :categories => ["C1_Arts_Culture_and_Humanities"],
+    :sub_categories => ["C1_Performing_Arts"]
+  }
+```
+
+### Organization Categories & Sub-Categories
+
+Categories (defaults to "C1_Arts_Culture_and_Humanities"):
+
+* "C1_Arts_Culture_and_Humanities"
+* "C2_Education_and_Research"
+* "C3_Environment_and_Animals"
+* "C4_Health"
+* "C5_Human_Services"
+* "C6_International"
+* "C7_Public_Societal_Benefit"
+* "C8_Religion"
+* "C9_Unknown"
+
+Sub-Categories (defaults to "C4_Performing_Arts"):
+
+* "C1_Humanities_and_Historical_Societies"
+* "C1_Media"
+* "C1_Museums"
+* "C1_Performing_Arts"
+* "C1_Service_and_Other"
+* "C2_College_and_University"
+* "C2_Elementary_and_Secondary"
+* "C2_Libraries"
+* "C2_Research_Institutes"
+* "C2_Service_and_Other"
+* "C2_Vocational_Technical_and_Adult"
+* "C3_Animal_Protection_Welfare_and_Services"
+* "C3_Beautification_and_Horticulture"
+* "C3_Conservation_and_Environmental_Education"
+* "C3_Health_Care_Facilities_and_Programs"
+* "C3_Pollution"
+* "C3_Service_and_Other"
+* "C3_Zoos_and_Veterinary_Services"
+* "C4_Addiction_and_Substance_Abuse"
+* "C4_Diseases_and_Disease_Research"
+* "C4_Health_Care_Facilities_and_Programs"
+* "C4_Medical_Disciplines_and_Specialty_Research"
+* "C4_Mental_Health_and_Crisis_Services"
+* "C5_Agriculture_Food_and_Nutrition"
+* "C5_Crime_and_Legal_Related"
+* "C5_Employment_and_Occupations"
+* "C5_General_Human_Services"
+* "C5_Housing"
+* "C5_Public_Safety_Disaster_Preparedness_and_Relief"
+* "C5_Recreation_and_Sports"
+* "C5_Youth_Development"
+* "C6_International_Development_and_Relief_Services"
+* "C6_International_Human_Rights"
+* "C6_International_Peace_and_Security"
+* "C6_Promotion_of_International_Understanding"
+* "C6_Service_and_Other"
+* "C7_Civil_Rights_and_Liberties"
+* "C7_Community_Improvement"
+* "C7_Mutual_or_Membership_Benefit_Organizations"
+* "C7_Philanthropy_Voluntarism_and_Public_Benefit"
+* "C7_Service_and_Other"
+* "C7_Voter_Education_and_Registration"
+* "C8_Buddhist"
+* "C8_Christian"
+* "C8_Hindu"
+* "C8_Islamic"
+* "C8_Jewish"
+* "C8_Religious_Media"
+* "C8_Service_and_Other"
+* "C9_Unknown"
+
+## Dependencies
+
+* [nokogiri](http://github.com/tenderlove/nokogiri)
+* [rest-client](http://github.com/archiloque/rest-client)
+
+## Copyright
+
+Copyright (c) 2012 Gemini SBS. See LICENSE for details.
+
+## Authors
+
+* [Mauricio Gomes](http://github.com/mgomes)

data/Rakefile

@@ -0,0 +1,22 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rake'
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "test #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/guidestar-ruby.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name = %q{guidestar-ruby}
+  s.summary = %q{A ruby wrapper around the Guidestar API}
+  s.description = %q{A ruby wrapper around the Guidestar API}
+  s.homepage = %q{http://github.com/geminisbs/guidestar-ruby}
+  s.version = File.read(File.join(File.dirname(__FILE__), 'VERSION'))
+  s.authors = ["Mauricio Gomes"]
+  s.email = "mgomes@geminisbs.com"
+
+  s.add_dependency "nokogiri", "~> 1.4.3.1"
+  s.add_dependency "rest-client", "~> 1.6.0"
+
+  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"]
+end

data/lib/guidestar-ruby.rb

@@ -0,0 +1,21 @@
+require 'uri'
+require 'nokogiri'
+require 'rest_client'
+
+require 'guidestar/connection'
+require 'guidestar/client'
+
+module Guidestar
+  VERSION = File.read(File.join(File.dirname(__FILE__), '..', 'VERSION'))
+  ENDPOINT = "https://gsservices.guidestar.org/GuideStar_SearchService/SearchService.asmx/GuideStarDetail"
+
+  class GuidestarError < StandardError; end
+  class InsufficientArgs < GuidestarError; end
+  class Unauthorized < GuidestarError; end
+  class NotFound < GuidestarError; end
+  class ServerError < GuidestarError; end
+  class Unavailable < GuidestarError; end
+  class Timeout < GuidestarError; end
+  class DecodeError < GuidestarError; end
+  class CredentialsNotSpecified < GuidestarError; end
+end

data/lib/guidestar.rb

@@ -0,0 +1,2 @@
+# So you can require "guidestar" instead of "guidestar-ruby"
+require "guidestar-ruby"

data/lib/guidestar/client.rb

@@ -0,0 +1,65 @@
+module Guidestar
+
+  class Client
+
+    @@default_options = { :version => "1.0", :pageSize => 25, :offset => 0 }
+    @@options_mapping = { :name => :orgName,
+                          :zip_radius => :zipradius,
+                          :ntee_code => :nteeCode,
+                          :page_size => :pageSize
+                        }
+
+    @@connection = nil
+
+    class << self
+
+      def set_credentials(username, password, proxy=nil)
+        @@connection = Connection.new(username, password, proxy)
+      end
+
+      def search(*args)
+        options = extract_options!(args)
+        options = translate_options(options)
+        result = post(@@default_options.merge(options))
+      end
+
+    private
+
+      def post(data)
+        raise CredentialsNotSpecified if @@connection.nil?
+        @@connection.post data
+      end
+
+      def decode_host(realm)
+        realm.split('/').delete_if {|i| i == 'index.html' }.join('/').gsub(':5058', '')
+      end
+
+      def extract_options!(args)
+        if args.last.is_a?(Hash)
+          return args.pop
+        else
+          return {}
+        end
+      end
+
+      def translate_options(options)
+        dup_options = {}
+        options.each_pair do |k,v|
+          if @@options_mapping[k]
+            dup_options[@@options_mapping[k]] = v
+          else
+            dup_options[k] = v
+          end
+        end
+
+        # Ensure EINs are in the format NN-NNNNNNN
+        dup_options[:ein].insert(2, '-') if dup_options[:ein] && dup_options[:ein][2] != '-'
+
+        dup_options
+      end
+
+    end
+
+  end
+
+end

data/lib/guidestar/connection.rb

@@ -0,0 +1,138 @@
+module Guidestar
+
+  class Connection
+
+    attr_reader :username, :password
+
+    def initialize(username, password, proxy=nil)
+      @username = username
+      @password = password
+      @proxy = proxy
+    end
+
+    def post(data)
+      request :post, data
+    end
+
+  private
+
+    def request(method, data)
+      response = send_request(method, construct_document(data))
+
+      deconstruct_document response
+    end
+
+    def send_request(method, data)
+      RestClient.proxy = @proxy unless @proxy.nil?
+
+      begin
+        response = RestClient.post(ENDPOINT, :xmlInput => data, :multipart => false)
+      rescue => e
+        raise_errors(e.response)
+      end
+
+      response
+    end
+
+    def construct_document(data)
+      builder = Nokogiri::XML::Builder.new do |xml|
+        xml.query {
+          xml.version data[:version]
+          xml.login @username
+          xml.password @password
+          xml.pageSize data[:pageSize]
+          xml.offset data[:offset]
+          xml.orgName data[:orgName]    if data[:orgName]
+          xml.ein data[:ein]            if data[:ein]
+          xml.city data[:city]          if data[:city]
+          xml.state data[:state]        if data[:state]
+          xml.zip data[:zip]            if data[:zip]
+          xml.nteeCode data[:nteeCode]  if data[:nteeCode]
+          if data[:categories] && data[:categories].is_a?(Array)
+            data[:categories].each {|category| xml.category category }
+          end
+
+          if data[:sub_categories] && data[:sub_categories].is_a?(Array)
+            data[:sub_categories].each {|sub_category| xml.subCategory sub_category }
+          end
+        }
+      end
+
+      builder.to_xml
+    end
+
+    def deconstruct_document(response)
+      organizations = []
+      raise(Timeout, "The Guidestar server could not be reached") if response.nil?
+
+      begin
+        doc = Nokogiri::XML.parse(CGI.unescapeHTML(response.body))
+        doc.remove_namespaces!
+        doc.xpath('//organizations/organization').each do |org|
+          organization = {}
+          org.xpath('.//generalInformation').each do |info|
+            organization[:name] = info.at('orgName').text.strip
+            organization[:ein] = info.at('ein').text.gsub('-', '')
+            organization[:website] = info.at('url').text
+            organization[:ruling_date] = info.at('rulingYear').text
+            organization[:asset_amount] = info.at('assets').text ? info.at('assets').text.to_i : nil
+            organization[:annual_revenue] = info.at('income').text ? info.at('income').text.to_i : nil
+            organization[:alternate_name] = info.at('aka').text
+
+            info.xpath('.//address').each do |address|
+              organization[:address] = address.at('addressLine1').text
+              organization[:address2] = address.at('addressLine2').text
+              organization[:city] = address.at('city').text
+              organization[:state] = address.at('state').text
+              organization[:zip] = address.at('zip').text
+            end
+
+            info.xpath('.//contact').each do |contact|
+              organization[:contact_name] = [contact.at('firstName').text, contact.at('lastName').text].join(' ')
+              organization[:email] = contact.at('email').text
+              organization[:phone] = contact.at('phone').text
+              organization[:fax] = contact.at('fax').text
+            end
+
+            organization[:non_profit] = true
+
+            organization[:ntees] = []
+            info.xpath('.//ntees/ntee').each do |ntee|
+              next if ntee.at('code').text == ""
+              organization[:ntees] << { :code => ntee.at('code').text, :description => ntee.at('description').text }
+            end
+
+          end
+
+          organizations << tidy_org(organization)
+        end
+      rescue
+        raise DecodeError, "content: <#{response.body}>"
+      end
+
+      organizations
+    end
+
+    def tidy_org(organization)
+      organization.each_pair do |k, v|
+        organization[k].strip! if v.class == String
+      end
+      organization
+    end
+
+    def raise_errors(response)
+      raise(Timeout, "The Guidestar server could not be reached") if response.nil?
+
+      case response.code
+        when 500
+          raise ServerError, "Guidestar server had an internal error. #{response.description}\n\n#{response.body}"
+        when 502..503
+          raise Unavailable, response.description
+        else
+          raise SemaphoreError, response.description
+      end
+    end
+
+  end
+
+end

data/spec/guidestar-ruby.rb

@@ -0,0 +1,7 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "Guidstar" do
+  it "fails" do
+    fail "hey buddy, you should probably rename this file and start specing for real"
+  end
+end

data/spec/spec.opts

@@ -0,0 +1,4 @@
+--colour
+--format nested
+--loadby mtime
+--backtrace

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'guidestar'
+require 'spec'
+require 'spec/autorun'
+
+Spec::Runner.configure do |config|
+
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: guidestar-ruby
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Mauricio Gomes
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-04-03 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: &70299699930800 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.4.3.1
+  type: :runtime
+  prerelease: false
+  version_requirements: *70299699930800
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: &70299699930260 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.6.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *70299699930260
+description: A ruby wrapper around the Guidestar API
+email: mgomes@geminisbs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- VERSION
+- guidestar-ruby.gemspec
+- lib/guidestar-ruby.rb
+- lib/guidestar.rb
+- lib/guidestar/client.rb
+- lib/guidestar/connection.rb
+- spec/guidestar-ruby.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+homepage: http://github.com/geminisbs/guidestar-ruby
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.16
+signing_key: 
+specification_version: 3
+summary: A ruby wrapper around the Guidestar API
+test_files:
+- spec/guidestar-ruby.rb
+- spec/spec.opts
+- spec/spec_helper.rb