rapleaf_api 0.1.5 → 1.2.0

data/CHANGELOG

@@ -0,0 +1,7 @@
+v1.2.0 Bump version number to match User-Agent
+
+v0.1.1. Bug fixes
+
+v0.1.0. Added support for show_available
+
+v0.0.1. Initial version

data/LICENSE

@@ -0,0 +1,19 @@
+* The Rapleaf Personalization API has separate terms and conditions, which can
+  be found at http://www.rapleaf.com/developers/api_usage.
+* If you send us code, please keep in mind that it will be distributed under
+  the same license as the rest of the project.
+* This code is licensed under the Apache License which follows...
+
+Copyright 2011 Rapleaf
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/Manifest

@@ -0,0 +1,7 @@
+CHANGELOG
+LICENSE
+Manifest
+README.md
+Rakefile
+lib/rapleaf_api.rb
+rapleaf_api.gemspec

data/README.md

@@ -1,51 +1,72 @@
-# rapleaf_api
-
-Getting Started
----------------
-
-You need to first get an API key found here:
-
-[http://www.rapleaf.com/developer/](http://www.rapleaf.com/developer/)
-  
+How to Use
+==========
 
 Installation
 ------------
+> gem install rapleaf_api
 
-	sudo gem install rapleaf_api
+This gem depends on the "json" gem.
 
 Usage
 -----
+    > require 'rapleaf_api'
+    => true
+    > api = RapleafApi::Api.new('my secret API key')
+    => #<RapleafApi::Api:0x101b7f5f0 @API_KEY="my secret API key", @CA_PATH=nil, @TIMEOUT=2, @BASE_PATH="/v4/dr?api_key=my secret API key">
+    > h = api.query_by_email('test@example.com')
+    => {"location"=>"Fakesville, California, United States", "gender"=>"Male", "age"=>"25-34"}
+
+Constructor Options
+-------------------
+You can pass in an options hash to the API constructor, like so:
+
+    > api = RapleafApi::Api.new('my secret API key', :timeout => 10)
+    => #<RapleafApi::Api:0x101b7f5f0 @API_KEY="my secret API key", @CA_PATH=nil, @TIMEOUT=10, @BASE_PATH="/v4/dr?api_key=my secret API key">
+
+The possible options/keys accepted by the constructor are:
+
+ - :timeout => The max amount of time to wait for a request to finish. Defaults to 2.
+ - :ca_path => Set this to your system-wide root CA cert path if you're having SSL verification issues. Defaults to nil.
+ 
+Query Options
+-------------
+The gem supports several ways to query Rapleaf's API: email, hashed email (either MD5 or SHA1 hash), name and postal (NAP), or name and ZIP+4 (NAZ).
+
+### query_by_email(email, options)
+
+This method queries Rapleaf's API with the specified email. The options hash accepts the following keys:
+
+ - :hash_email    => Whether to (SHA1) hash the email before querying Rapleaf's API with it. Defaults to nil.
+ - :show_availble => Controls whether the response will include information about available data---i.e., data for fields the API account is not subscribed to but for which Rapleaf has data. If this option is turned on, fields will be filled in with the string "Data Available". Defaults to nil.
+
+### query_by_md5(md5_email, options)
+### query_by_sha1(sha1_email, options)
+
+These methods query Rapleaf's API with the specified email hashes (either MD5 or SHA1, respectively). Both methods accept an options hash with the following keys:
 
-	require 'rubygems'
-	require 'rapleaf_api'
+ - :show_available => Controls whether the response will include information about available data. Defaults to nil.
+ 
+### query_by_nap(first, last, street, city, state, options)
 
-	rapAPI = RapleafApi::Api.new("your api key")
-	
-### Person API
+This method queries Rapleaf's API with a name and postal address: first name, last name, street, city, and state acronym (i.e., the state's 2-character postal code). It also accepts the following options hash:
 
-	#by email
-	person = rapAPI.query({:type => :person, {:email => "email"}})
+ - :email          => You can include an email in your NAP query to increase the hit rate. Defaults to nil.
+ - :show_available => Controls whether the response will include information about available data. Defaults to nil.
 
-	#by md5 hash of email
-	person = rapAPI.query({:type => :person, {:hash => RapleafApi::MD5, :id => "md5 hash of email"}})
+### query_by_naz(first, last, zip4, options)
 
-	#by site id
-	person = rapAPI.query({:type => :person, {:site => RapleafApi::TWITTER, :id => "twitter username"}})
+This method queries Rapleaf's API with a name and ZIP+4 code. The ZIP+4 is a string with a 5-digit ZIP code and 4-digit extension separated by a dash. This method accepts the following options:
 
-### Graph API
+- :email          => You can include an email in your NAP query to increase the hit rate. Defaults to nil.
+- :show_available => Controls whether the response will include information about available data. Defaults to nil.
 
-	#by email (note this query will only work if you have an email set stored with Rapleaf)
-	friendList = rapAPI.query({:type => :graph, {:id => "email address"}})
 
-	#by email, return Rapleaf IDs instead of scoped emails
-	friendList = rapAPI.query({:type => :graph, {:id => "email address", :return_rapid => true}})
+Contributing
+============
+If you have suggestions or patches, feel free to email us at
+<developer at rapleaf dot com>. We look forward to hearing from you!
 
-	#by Rapleaf ID, this will return a list of Rapleaf IDs
-	friendList = rapAPI.query({:type => :graph, {:id => "rapleaf id", :by_rapid => true}})
-	
-Authors
--------
 
-* [Adam Coffman](http://github.com/thecoffman) :: coffman.adam@gmail.com
-* [Brent Beer](http://github.com/brntbeer) :: brentbeer@gmail.com
-* [Mark Sands](http://github.com/marksands) :: marksands07@gmail.com
+Contributors
+============
+Greg Poulos <greg at rapleaf dot com>

data/Rakefile

@@ -0,0 +1,13 @@
+require 'rubygems'
+require 'rake'
+require 'echoe'
+
+Echoe.new('rapleaf_api', '1.2.0') do |p|
+  p.author         = 'Rapleaf'
+  p.description    = "A library for interacting with Rapleaf's Personalization API."
+  p.email          = 'developer @nospam@ rapleaf.com'
+  p.url            = 'http://www.rapleaf.com'
+  p.ignore_pattern = ["tmp/*"]
+  p.development_dependencies = ['echoe']
+  p.runtime_dependencies = ['json']
+end

data/lib/rapleaf_api.rb

@@ -1,29 +1,134 @@
-require 'rubygems'
-require 'net/http'
-require 'xmlsimple'
+# Copyright 2010 Rapleaf
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
 
-%w{api.rb person.rb graph.rb errors.rb}.each do |file|
-  require File.dirname(__FILE__) +"/api/" + file
-end
-
-module RapleafApi
+require "rubygems"
+require "json"
+require "net/https"
+require "timeout"
+require "erb"
+require "digest"
 
-  VERSION = '0.1.0'
+include ERB::Util
 
-  #Constants for web queries
-  BEBO = "bebo"
-  FACEBOOK = "facebook"
-  FLICKR = "flickr"
-  FRIENDSTER = "friendster"
-  HI5 = "hi5"
-  LINKEDIN = "linkedin"
-  MYSPACE = "myspace"
-  PLAXO = "plaxo"
-  RAPLEAF = "rapleaf"
-  TWITTER = "twitter"
-
-  #constants for hash types
-  MD5 = "md5"
-  SHA1 = "sha1"
+module RapleafApi
+  HOST = "personalize.rapleaf.com"
+  PORT = 443
+  HEADERS = {'User-Agent' => 'RapleafApi/Ruby/1.2.0'}
 
+  class Api
+    def initialize(api_key, options = {})
+      @API_KEY = api_key
+      @BASE_PATH = "/v4/dr?api_key=#{@API_KEY}"
+      @TIMEOUT = options[:timeout] || 2
+      @CA_PATH = options[:ca_path] # set to your system-wide root ca cert path 
+                                   # if you're having ssl verification issues
+    end
+  
+    # Takes an e-mail and returns a hash which maps attribute fields onto attributes
+    # Options:
+    #  :hash_email     - the email will be hashed before it's sent to Rapleaf
+    #  :show_available - return the string "Data Available" for fields the API 
+    #                    account is not subscribed to but for which Rapleaf has data
+    def query_by_email(email, options = {})
+      if options[:hash_email]
+        query_by_sha1(Digest::SHA1.hexdigest(email), :show_available => options[:show_available])
+      else
+        get_json_response("#{@BASE_PATH}&email=#{url_encode(email)}", options[:show_available])
+      end
+    end
+  
+    # Takes an e-mail that has already been hashed by md5
+    # and returns a hash which maps attribute fields onto attributes,
+    # optionally showing available data in the response
+    def query_by_md5(md5_email, options = {})
+      get_json_response("#{@BASE_PATH}&md5_email=#{url_encode(md5_email)}", options[:show_available])
+    end
+  
+    # Takes an e-mail that has already been hashed by sha1
+    # and returns a hash which maps attribute fields onto attributes,
+    # optionally showing available data in the response
+    def query_by_sha1(sha1_email, options = {})
+      get_json_response("#{@BASE_PATH}&sha1_email=#{url_encode(sha1_email)}", options[:show_available])
+    end
+  
+    # Takes first name, last name, and postal (street, city, and state acronym),
+    # and returns a hash which maps attribute fields onto attributes
+    # Options:
+    #  :email          - query with an email to increase the hit rate
+    #  :show_available - return the string "Data Available" for fields 
+    #                    the API account is not subscribed to but for 
+    #                    which Rapleaf has data
+    def query_by_nap(first, last, street, city, state, options = {})
+      if options[:email]
+        url = "#{@BASE_PATH}&email=#{url_encode(options[:email])}&first=#{url_encode(first)}&last=#{url_encode(last)}" +
+        "&street=#{url_encode(street)}&city=#{url_encode(city)}&state=#{url_encode(state)}"
+      else
+        url = "#{@BASE_PATH}&first=#{url_encode(first)}&last=#{url_encode(last)}" +
+        "&street=#{url_encode(street)}&city=#{url_encode(city)}&state=#{url_encode(state)}"
+      end
+      get_json_response(url, options[:show_available])
+    end
+  
+    # Takes first name, last name, and zip4 code (5-digit zip 
+    # and 4-digit extension separated by a dash as a string),
+    # and returns a hash which maps attribute fields onto attributes
+    # Options:
+    #  :email          - query with an email to increase the hit rate
+    #  :show_available - return the string "Data Available" for fields 
+    #                    the API account is not subscribed to but for 
+    #                    which Rapleaf has data
+    def query_by_naz(first, last, zip4, options = {})
+      if options[:email]
+        url = "#{@BASE_PATH}&email=#{url_encode(options[:email])}&first=#{url_encode(first)}&last=#{url_encode(last)}&zip4=#{zip4}"
+      else
+        url = "#{@BASE_PATH}&first=#{url_encode(first)}&last=#{url_encode(last)}&zip4=#{zip4}"
+      end
+      get_json_response(url, options[:show_available])
+    end
+  
+    private
+  
+    # Takes a url and returns a hash mapping attribute fields onto attributes
+    # Note that an exception is raised in the case that
+    # an HTTP response code other than 200 is sent back
+    # The error code and error body are put in the exception's message
+    def get_json_response(path, show_available = false)
+      path += "&show_available" if show_available
+      response = Timeout::timeout(@TIMEOUT) do
+        begin
+          http_client.get(path, HEADERS)
+        rescue EOFError # Connection cut out. Just try a second time.
+          http_client.get(path, HEADERS)
+        end
+      end
+      if response.code =~ /^2\d\d/
+        (response.body && response.body != "") ? JSON.parse(response.body) : {}
+      else
+        raise "Error Code #{response.code}: \"#{response.body}\""
+      end
+    end
+  
+    # Returns http connection to HOST on PORT
+    def http_client
+      unless defined?(@@http_client)
+        @@http_client = Net::HTTP.new(HOST, PORT)
+        @@http_client.use_ssl = true
+        @@http_client.ca_path = @CA_PATH if @CA_PATH
+        @@http_client.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        @@http_client.start
+      end
+      @@http_client
+    end
+  end
 end

data/rapleaf_api.gemspec

@@ -0,0 +1,35 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{rapleaf_api}
+  s.version = "1.2.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Rapleaf"]
+  s.date = %q{2011-03-11}
+  s.description = %q{A library for interacting with Rapleaf's Personalization API.}
+  s.email = %q{developer @nospam@ rapleaf.com}
+  s.extra_rdoc_files = ["CHANGELOG", "LICENSE", "README.md", "lib/rapleaf_api.rb"]
+  s.files = ["CHANGELOG", "LICENSE", "Manifest", "README.md", "Rakefile", "lib/rapleaf_api.rb", "rapleaf_api.gemspec"]
+  s.homepage = %q{http://www.rapleaf.com}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Rapleaf_api", "--main", "README.md"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{rapleaf_api}
+  s.rubygems_version = %q{1.6.2}
+  s.summary = %q{A library for interacting with Rapleaf's Personalization API.}
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<json>, [">= 0"])
+      s.add_development_dependency(%q<echoe>, [">= 0"])
+    else
+      s.add_dependency(%q<json>, [">= 0"])
+      s.add_dependency(%q<echoe>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<json>, [">= 0"])
+    s.add_dependency(%q<echoe>, [">= 0"])
+  end
+end

metadata

@@ -1,75 +1,109 @@
 --- !ruby/object:Gem::Specification 
 name: rapleaf_api
 version: !ruby/object:Gem::Version 
-  version: 0.1.5
+  hash: 31
+  prerelease: 
+  segments: 
+  - 1
+  - 2
+  - 0
+  version: 1.2.0
 platform: ruby
 authors: 
-- Adam Coffman
-- Brent Beer
-- Mark Sands
+- Rapleaf
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2010-02-12 00:00:00 -06:00
+date: 2011-03-11 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: xml-simple
+  name: json
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
   type: :runtime
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: echoe
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
         version: "0"
-    version: 
-description: An interface to Rapleaf's person and graph APIs. Note that this library is not maintained by or affiliated with Rapleaf in any way and you will still need a (free) api key from Rapleaf to use this.
-email: 
-- coffman.adam@gmail.com
-- brent.beer@gmail.com
-- marksands07@gmail.com
+  type: :development
+  version_requirements: *id002
+description: A library for interacting with Rapleaf's Personalization API.
+email: developer @nospam@ rapleaf.com
 executables: []
 
 extensions: []
 
-extra_rdoc_files: []
-
+extra_rdoc_files: 
+- CHANGELOG
+- LICENSE
+- README.md
+- lib/rapleaf_api.rb
 files: 
+- CHANGELOG
+- LICENSE
+- Manifest
 - README.md
-- Manifest.txt
+- Rakefile
 - lib/rapleaf_api.rb
-- lib/api/api.rb
-- lib/api/graph.rb
-- lib/api/person.rb
-- lib/api/errors.rb
+- rapleaf_api.gemspec
 has_rdoc: true
-homepage: http://github.com/thecoffman/rapleaf_api
+homepage: http://www.rapleaf.com
 licenses: []
 
 post_install_message: 
-rdoc_options: []
-
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Rapleaf_api
+- --main
+- README.md
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      version: "0"
-  version: 
+      hash: 11
+      segments: 
+      - 1
+      - 2
+      version: "1.2"
 requirements: []
 
-rubyforge_project: 
-rubygems_version: 1.3.5
+rubyforge_project: rapleaf_api
+rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
-summary: An interface to Rapleaf's person and graph APIs.
+summary: A library for interacting with Rapleaf's Personalization API.
 test_files: []
 

data/Manifest.txt

@@ -1,8 +0,0 @@
-Manifest.txt
-README.txt
-Rakefile
-lib/rapleaf_api.rb
-lib/api/api.rb
-lib/api/graph.rb
-lib/api/person.rb
-lib/api/errors.rb

data/lib/api/api.rb

@@ -1,85 +0,0 @@
-module RapleafApi
-  class Api
-
-    def initialize(api_key)
-      @API_KEY = "?api_key=#{api_key}"
-      @PERSON_URL = "http://api.rapleaf.com/v3/person/"
-      @GRAPH_URL = "http://api.rapleaf.com/v2/graph/"
-    end
-
-    def query(params)
-			raise InvalidParams, "Invalid query, please use an :opts hash to specify your options" unless !params[:opts].nil?
-      case params[:type]
-				when :person
-          return Person.new(person_request(params[:opts]))
-        when :graph
-          return Graph.new(graph_request(params[:opts]))
-        else
-          raise InvalidParams, "Invalid query type, use either :graph or :person"
-      end
-    end
-
-    private
-
-    def request(url)
-      resp = Net::HTTP.get_response(URI.parse(url))
-      if resp.code == "200"
-        return resp.body
-      else
-        raise_response_errors(resp.code)
-      end
-    end
-
-    def person_request(params)
-      raise InvalidParams, "Your params hash was formatted incorrectly!" unless url = verify_and_build_person_url(params)
-      request(url)
-    end
-
-    def graph_request(params)
-      raise InvalidParams, "Your params hash was formatted incorrectly!" unless url = verify_and_build_graph_url(params)
-      request(url)
-    end
-
-    def verify_and_build_person_url(params)
-      if params.size == 1
-        return false unless params[:email]
-        return @PERSON_URL + "email/#{params[:email]}" + @API_KEY
-      else
-        return false unless params[:id] && (params[:hash] || params[:site])
-        return @PERSON_URL + (!params[:hash].nil? ? "hash/#{params[:hash]}/#{params[:id]}" : "web/#{params[:site]}/#{params[:id]}") + @API_KEY 
-      end
-    end
-
-    def verify_and_build_graph_url(params)
-      if params.size == 1
-        return false unless params[:id]
-        return @GRAPH_URL + params[:id] + @API_KEY
-      elsif params.size == 2
-        return false unless params[:id] && (params[:by_rapid] || params[:return_rapid])
-        return @GRAPH_URL + params[:id] + @API_KEY + "&" + ( !params[:by_rapid].nil? ? "n=2" : "n=1")
-      else
-        return false
-      end
-    end
-
-    def raise_response_errors(code)
-      case code 
-        when "202"
-          raise AcceptedException, "This person is currently being searched. Please check back shortly."
-        when "400"
-          raise MalformedRequestException, "Malformed request."
-        when "401"
-          raise ApiKeyInvalidException, "API Key invalid"
-        when "403"
-          raise RateLimitExceededException, "API Key query limit exceded, please contact developer@rapleaf.com to have your limit increased."
-        when "404"
-          raise PersonNotFoundException, "We do not have this person in our system. If you would like better results, consider supplying the email address."
-        when "500"
-          raise InternalServerError, "There was an unexpected error on our server. This should be very rare and if you see it please contact developer@rapleaf.com."
-        else
-          raise "Unkown Error"
-      end
-    end
-
-  end
-end

data/lib/api/errors.rb

@@ -1,26 +0,0 @@
-module RapleafApi
-  
-  class InvalidParams < Exception
-  end
-
-  class AcceptedException < Exception
-  end
-
-  class MalformedRequestException < Exception
-  end
-
-  class ApiKeyInvalidException < Exception
-  end
-
-  class RateLimitExceededException < Exception
-  end
-
-  class PersonNotFoundException < Exception
-  end
-
-  class InternalServerError < Exception
-  end
-
-end
-
-

data/lib/api/graph.rb

@@ -1,17 +0,0 @@
-module RapleafApi
-  class Graph
-  
-    def initialize( body )
-      @body = body
-    end
-  
-    def friends
-			if @body.include?(",")
-				@body.split(",")
-			else
-      	@body.split("\n")
-			end
-    end
-
-  end
-end

data/lib/api/person.rb

@@ -1,72 +0,0 @@
-module RapleafApi
-
-	class Person
-
-		def initialize(xml)
- 			@xml = XmlSimple.xml_in(xml, {'ForceArray' => false,
-                                    'GroupTags' =>{'primary' => 'membership',
-																			             'supplemental' => 'membership',
-																									 'universities' => 'university',
-			                                             'occupations' =>'occupation'}})
-		end
-
-		def rapleaf_id
-			@xml["id"]
-		end
-
-		def basics
-			@xml["basics"]
-		end
-
-		def name
-		  @xml["basics"]["name"]
-		end
-
-		def age
-			@xml["basics"]["age"]
-		end
-
-		def gender
-			@xml["basics"]["gender"]
-		end
-
-		def location
-			@xml["basics"]["location"]
-		end
-
-		def occupations
-			@xml["basics"]["occupations"]
-		end
-
-		def universities
-			@xml["basics"]["universities"]
-		end
-
-		def earliest_known_activity
-			@xml["basics"]["earliest_known_activity"]
-		end
-
-		def last_known_activity
-			@xml["basics"]["latest_known_activity"]
-		end
-
-		def num_friends
-			@xml["basics"]["num_friends"]
-		end
-
-		def memberships(selection = :all)
-			if selection == :primary || selection == :all
-				memberships = (@xml["memberships"]["primary"])
-			end
-			if selection == :supplemental || selection == :all
-			  if memberships.nil?
-			    memberships = (@xml["memberships"]["supplemental"])
-		    else
-				  memberships << (@xml["memberships"]["supplemental"])
-			  end
-			end
-			memberships.compact
-		end
-	end
-
-end