piplapis-ruby 4.0.0

data/LICENSE

@@ -0,0 +1,11 @@
+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/README.md

@@ -0,0 +1,38 @@
+piplapis Ruby Library
+===========================
+
+This is a Ruby client library for easily integrating Pipl's APIs into your application.
+
+* Full details about Pipl's APIs - [http://dev.pipl.com](http://dev.pipl.com)  
+* This library is available in other languages - [http://dev.pipl.com/docs/libraries](http://dev.pipl.com/docs/libraries)
+
+Library Requirements
+--------------------
+
+* Ruby 1.9 and above.
+
+Library Notes
+-------------
+
+* According to the [documentation](http://dev.pipl.com/docs/read/search_api/data#fields-objects) some field objects should have a `.display` attribute,
+since this is reserved in Ruby this attribute was renamed to `.show`.
+
+Getting Started & Code Snippets
+-------------------------------
+
+**Pipl's Search API**
+* Getting started tutorial - [http://dev.pipl.com/docs/search_api/getstarted](http://dev.pipl.com/docs/search_api/getstarted)  
+* Code snippets - [http://dev.pipl.com/docs/search_api/code](http://dev.pipl.com/docs/search_api/code)  
+
+**Pipl's Name API**
+* Getting started tutorial - [http://dev.pipl.com/docs/name_api/getstarted](http://dev.pipl.com/docs/name_api/getstarted)  
+* Code snippets - [http://dev.pipl.com/docs/name_api/code](http://dev.pipl.com/docs/name_api/code)  
+
+**Pipl's Thumbnail API**
+* Getting started tutorial - [http://dev.pipl.com/docs/thumbnail_api/getstarted](http://dev.pipl.com/docs/thumbnail_api/getstarted)  
+* Code snippets - [http://dev.pipl.com/docs/thumbnail_api/code](http://dev.pipl.com/docs/thumbnail_api/code)  
+
+Credits
+-------
+
+Thanks to [srochy](https://github.com/srochy) for writing this library!

data/lib/pipl.rb

@@ -0,0 +1,35 @@
+require_relative 'pipl/client'
+require_relative 'pipl/default'
+
+module Pipl
+
+  class << self
+    include Pipl::Configurable
+
+    attr_accessor :logger
+
+    def client
+      @client = Client.new(options) unless defined?(@client) && @client.same_options?(options)
+      @client
+    end
+
+
+    def respond_to_missing?(method_name, include_private=false)
+      ; client.respond_to?(method_name, include_private);
+    end if RUBY_VERSION >= '1.9'
+
+    def respond_to?(method_name, include_private=false)
+      ; client.respond_to?(method_name, include_private) || super;
+    end if RUBY_VERSION < '1.9'
+
+    private
+
+    def method_missing(method_name, *args, &block)
+      return super unless client.respond_to?(method_name)
+      client.send(method_name, *args, &block)
+    end
+
+  end
+end
+
+Pipl.setup

data/lib/pipl/client.rb

@@ -0,0 +1,165 @@
+require 'uri'
+require 'net/http'
+
+require_relative 'configurable'
+require_relative 'containers'
+require_relative 'errors'
+require_relative 'fields'
+require_relative 'response'
+
+
+module Pipl
+
+  class Client
+
+    include Pipl::Configurable
+
+    def initialize(options = {})
+      Pipl::Configurable.keys.each do |key|
+        instance_variable_set(:"@#{key}", options[key] || Pipl.instance_variable_get(:"@#{key}"))
+      end
+
+    end
+
+    def same_options?(opts)
+      opts.hash == options.hash
+    end
+
+    def search(params={})
+      opts = options.merge params
+      create_search_person(opts)
+      validate_search_params(opts)
+      http, req = create_http_request(opts)
+      if opts.key? :callback
+        do_send_async http, req, opts[:callback]
+      elsif opts[:async] and block_given?
+        do_send_async http, req, Proc.new
+      else
+        do_send http, req
+      end
+    end
+
+    private
+
+    def create_search_person(opts)
+      return if opts.key? :search_pointer
+
+      person = opts[:person] || Pipl::Person.new
+      person.add_field Pipl::Name.new(raw: opts[:raw_name]) if opts[:raw_name]
+      person.add_field Pipl::Email.new(address: opts[:email]) if opts[:email]
+      person.add_field Pipl::Username.new(content: opts[:username]) if opts[:username]
+      person.add_field Pipl::Address.new(raw: opts[:raw_address]) if opts[:raw_address]
+
+      if opts[:first_name] || opts[:middle_name] || opts[:last_name]
+        person.add_field Pipl::Name.new(first: opts[:first_name], middle: opts[:middle_name], last: opts[:last_name])
+      end
+
+      if opts[:country] || opts[:state] || opts[:city]
+        person.add_field Pipl::Address.new(country: opts[:country], state: opts[:state], city: opts[:city])
+      end
+
+      if opts[:phone]
+        if opts[:phone].is_a? String
+          person.add_field Pipl::Phone.new(raw: opts[:phone])
+        else
+          person.add_field Pipl::Phone.new(number: opts[:phone])
+        end
+      end
+
+      if opts[:from_age] || opts[:to_age]
+        person.add_field Pipl::DOB.from_age_range((opts[:from_age] || 0).to_i, (opts[:to_age].to_i || 1000).to_i)
+      end
+
+      opts[:person] = person
+    end
+
+    def validate_search_params(opts)
+      unless opts[:api_key] and not opts[:api_key].empty?
+        raise ArgumentError.new('API key is missing')
+      end
+
+      if opts[:search_pointer] and opts[:search_pointer].empty?
+        raise ArgumentError.new('Given search pointer is empty')
+      end
+
+      unless opts.key? :search_pointer
+        unless opts[:person] and opts[:person].is_searchable?
+          raise ArgumentError.new('At least one valid name/username/phone/email is required for search')
+        end
+      end
+
+      if opts[:strict_validation]
+        if opts[:minimum_probability] and not (0..1).include? opts[:minimum_probability]
+          raise ArgumentError.new('minimum_probability must be a float in 0..1')
+        end
+
+        if opts[:minimum_match] and not (0..1).include? opts[:minimum_match]
+          raise ArgumentError.new('minimum_match must be a float in 0..1')
+        end
+
+        unless [Pipl::Configurable::SHOW_SOURCES_ALL,
+                Pipl::Configurable::SHOW_SOURCES_MATCHING,
+                Pipl::Configurable::SHOW_SOURCES_NONE, nil].include? opts[:show_sources]
+          raise ArgumentError.new('show_sources must be one of all, matching or false')
+        end
+
+        unless opts.key? :search_pointer
+          unsearchable = opts[:person].unsearchable_fields
+          if unsearchable and not unsearchable.empty?
+            raise ArgumentError.new("Some fields are unsearchable: #{unsearchable}")
+          end
+        end
+      end
+    end
+
+    def create_http_request(opts)
+      uri = URI(opts[:api_endpoint])
+      keys = %w(minimum_probability minimum_match hide_sponsored live_feeds show_sources)
+      query_params = ["key=#{opts[:api_key]}"] + keys.map { |k| "#{k}=#{opts[k.to_sym]}" unless opts[k.to_sym].nil? }
+      uri.query = query_params.compact.join('&')
+
+      req = Net::HTTP::Post.new(uri.request_uri)
+      req['User-Agent'] = opts[:user_agent]
+      if opts.key? :search_pointer
+        req.set_form_data search_pointer: opts[:search_pointer]
+      else
+        h = opts[:person].to_hash
+        req.set_form_data person: h.reject { |_, value| value.nil? }.to_json
+      end
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.open_timeout = opts[:http_timeout]
+
+      [http, req]
+    end
+
+    def do_send(http, req)
+      response = http.request(req)
+      if response.is_a? Net::HTTPSuccess
+        SearchResponse.from_json(response.body)
+      else
+        begin
+          err = Pipl::Client::APIError.from_json(response.body)
+        rescue
+          err = Pipl::Client::APIError.new response.message, response.code
+        end
+        raise err
+      end
+    end
+
+    def do_send_async(http, req, callback)
+      Thread.new do
+        begin
+          response = do_send http, req
+          callback.call response: response
+        rescue Pipl::Client::APIError => err
+          callback.call error: err
+        rescue Exception => msg
+          callback.call error: msg
+        end
+      end
+    end
+
+  end
+end

data/lib/pipl/configurable.rb

@@ -0,0 +1,55 @@
+module Pipl
+
+  module Configurable
+
+    SHOW_SOURCES_ALL = 'all'
+    SHOW_SOURCES_MATCHING = 'matching'
+    SHOW_SOURCES_NONE = 'false'
+
+    attr_accessor :api_key, :minimum_probability, :minimum_match, :hide_sponsored, :live_feeds, :show_sources
+    attr_accessor :strict_validation, :user_agent
+    attr_writer :api_endpoint
+
+    class << self
+
+      def keys
+        @keys ||= [
+            :api_key,
+            :minimum_probability,
+            :minimum_match,
+            :hide_sponsored,
+            :live_feeds,
+            :show_sources,
+            :strict_validation,
+            :api_endpoint,
+            :user_agent
+        ]
+      end
+
+    end
+
+    def configure
+      yield self
+    end
+
+    def reset!
+      Pipl::Configurable.keys.each do |key|
+        instance_variable_set(:"@#{key}", Pipl::Default.options[key])
+      end
+      self
+    end
+
+    alias setup reset!
+
+    def api_endpoint
+      File.join(@api_endpoint, '')
+    end
+
+    private
+
+    def options
+      Hash[Pipl::Configurable.keys.map { |key| [key, instance_variable_get(:"@#{key}")] }]
+    end
+
+  end
+end

data/lib/pipl/consts.rb

@@ -0,0 +1,74 @@
+# -*- encoding: utf-8 -*-
+
+module Pipl
+
+  DATE_FORMAT = '%Y-%m-%d'
+
+  STATES = {
+      US: {WA: 'Washington', VA: 'Virginia', DE: 'Delaware', DC: 'District Of Columbia', WI: 'Wisconsin',
+           WV: 'West Virginia', HI: 'Hawaii', FL: 'Florida', YT: 'Yukon', WY: 'Wyoming', PR: 'Puerto Rico',
+           NJ: 'New Jersey', NM: 'New Mexico', TX: 'Texas', LA: 'Louisiana', NC: 'North Carolina', ND: 'North Dakota',
+           NE: 'Nebraska', FM: 'Federated States Of Micronesia', TN: 'Tennessee', NY: 'New York', PA: 'Pennsylvania',
+           CT: 'Connecticut', RI: 'Rhode Island', NV: 'Nevada', NH: 'New Hampshire', GU: 'Guam', CO: 'Colorado',
+           VI: 'Virgin Islands', AK: 'Alaska', AL: 'Alabama', AS: 'American Samoa', AR: 'Arkansas', VT: 'Vermont',
+           IL: 'Illinois', GA: 'Georgia', IN: 'Indiana', IA: 'Iowa', MA: 'Massachusetts', AZ: 'Arizona',
+           CA: 'California', ID: 'Idaho', PW: 'Pala', ME: 'Maine', MD: 'Maryland', OK: 'Oklahoma', OH: 'Ohio',
+           UT: 'Utah', MO: 'Missouri', MN: 'Minnesota', MI: 'Michigan', MH: 'Marshall Islands', KS: 'Kansas',
+           MT: 'Montana', MP: 'Northern Mariana Islands', MS: 'Mississippi', SC: 'South Carolina', KY: 'Kentucky',
+           OR: 'Oregon', SD: 'South Dakota'},
+      CA: {AB: 'Alberta', BC: 'British Columbia', MB: 'Manitoba', NB: 'New Brunswick', NT: 'Northwest Territories',
+           NS: 'Nova Scotia', NU: 'Nunavut', ON: 'Ontario', PE: 'Prince Edward Island', QC: 'Quebec',
+           SK: 'Saskatchewan', YU: 'Yukon', NL: 'Newfoundland and Labrador'},
+      AU: {WA: 'State of Western Australia', SA: 'State of South Australia', NT: 'Northern Territory',
+           VIC: 'State of Victoria', TAS: 'State of Tasmania', QLD: 'State of Queensland',
+           NSW: 'State of New South Wales', ACT: 'Australian Capital Territory'},
+      GB: {WLS: 'Wales', SCT: 'Scotland', NIR: 'Northern Ireland', ENG: 'England'}
+  }
+
+  COUNTRIES = {BD: 'Bangladesh', WF: 'Wallis And Futuna Islands', BF: 'Burkina Faso', PY: 'Paraguay',
+               BA: 'Bosnia And Herzegovina', BB: 'Barbados', BE: 'Belgium', BM: 'Bermuda', BN: 'Brunei Darussalam',
+               BO: 'Bolivia', BH: 'Bahrain', BI: 'Burundi', BJ: 'Benin', BT: 'Bhutan', JM: 'Jamaica',
+               BV: 'Bouvet Island', BW: 'Botswana', WS: 'Samoa', BR: 'Brazil', BS: 'Bahamas', JE: 'Jersey',
+               BY: 'Belarus', BZ: 'Belize', RU: 'Russian Federation', RW: 'Rwanda', LT: 'Lithuania', RE: 'Reunion',
+               TM: 'Turkmenistan', TJ: 'Tajikistan', RO: 'Romania', LS: 'Lesotho', GW: 'Guinea-bissa', GU: 'Guam',
+               GT: 'Guatemala', GS: 'South Georgia And South Sandwich Islands', GR: 'Greece', GQ: 'Equatorial Guinea',
+               GP: 'Guadeloupe', JP: 'Japan', GY: 'Guyana', GG: 'Guernsey', GF: 'French Guiana', GE: 'Georgia',
+               GD: 'Grenada', GB: 'Great Britain', GA: 'Gabon', GN: 'Guinea', GM: 'Gambia', GL: 'Greenland',
+               GI: 'Gibraltar', GH: 'Ghana', OM: 'Oman', TN: 'Tunisia', JO: 'Jordan', HR: 'Croatia', HT: 'Haiti',
+               SV: 'El Salvador', HK: 'Hong Kong', HN: 'Honduras', HM: 'Heard And Mcdonald Islands', AD: 'Andorra',
+               PR: 'Puerto Rico', PS: 'Palestine', PW: 'Pala', PT: 'Portugal', SJ: 'Svalbard And Jan Mayen Islands',
+               VG: 'Virgin Islands, British', AI: 'Anguilla', KP: 'North Korea', PF: 'French Polynesia',
+               PG: 'Papua New Guinea', PE: 'Per', PK: 'Pakistan', PH: 'Philippines', PN: 'Pitcairn', PL: 'Poland',
+               PM: 'Saint Pierre And Miquelon', ZM: 'Zambia', EH: 'Western Sahara', EE: 'Estonia', EG: 'Egypt',
+               ZA: 'South Africa', EC: 'Ecuador', IT: 'Italy', AO: 'Angola', KZ: 'Kazakhstan', ET: 'Ethiopia',
+               ZW: 'Zimbabwe', SA: 'Saudi Arabia', ES: 'Spain', ER: 'Eritrea', ME: 'Montenegro', MD: 'Moldova',
+               MG: 'Madagascar', MA: 'Morocco', MC: 'Monaco', UZ: 'Uzbekistan', MM: 'Myanmar', ML: 'Mali', MO: 'Maca',
+               MN: 'Mongolia', MH: 'Marshall Islands', US: 'United States', UM: 'United States Minor Outlying Islands',
+               MT: 'Malta', MW: 'Malawi', MV: 'Maldives', MQ: 'Martinique', MP: 'Northern Mariana Islands',
+               MS: 'Montserrat', NA: 'Namibia', IM: 'Isle Of Man', UG: 'Uganda', MY: 'Malaysia', MX: 'Mexico',
+               IL: 'Israel', BG: 'Bulgaria', FR: 'France', AW: 'Aruba', AX: 'Åland', FI: 'Finland',
+               FJ: 'Fiji', FK: 'Falkland Islands', FM: 'Micronesia', FO: 'Faroe Islands', NI: 'Nicaragua',
+               NL: 'Netherlands', NO: 'Norway', SO: 'Somalia', NC: 'New Caledonia', NE: 'Niger', NF: 'Norfolk Island',
+               NG: 'Nigeria', NZ: 'New Zealand', NP: 'Nepal', NR: 'Naur', NU: 'Niue', MR: 'Mauritania',
+               CK: 'Cook Islands', CI: "Côte D'ivoire", CH: 'Switzerland', CO: 'Colombia', CN: 'China',
+               CM: 'Cameroon', CL: 'Chile', CC: 'Cocos (keeling) Islands', CA: 'Canada', CG: 'Congo (brazzaville)',
+               CF: 'Central African Republic', CD: 'Congo (kinshasa)', CZ: 'Czech Republic', CY: 'Cyprus',
+               CX: 'Christmas Island', CS: 'Serbia', CR: 'Costa Rica', HU: 'Hungary', CV: 'Cape Verde', CU: 'Cuba',
+               SZ: 'Swaziland', SY: 'Syria', KG: 'Kyrgyzstan', KE: 'Kenya', SR: 'Suriname', KI: 'Kiribati',
+               KH: 'Cambodia', KN: 'Saint Kitts And Nevis', KM: 'Comoros', ST: 'Sao Tome And Principe', SK: 'Slovakia',
+               KR: 'South Korea', SI: 'Slovenia', SH: 'Saint Helena', KW: 'Kuwait', SN: 'Senegal', SM: 'San Marino',
+               SL: 'Sierra Leone', SC: 'Seychelles', SB: 'Solomon Islands', KY: 'Cayman Islands', SG: 'Singapore',
+               SE: 'Sweden', SD: 'Sudan', DO: 'Dominican Republic', DM: 'Dominica', DJ: 'Djibouti', DK: 'Denmark',
+               DE: 'Germany', YE: 'Yemen', AT: 'Austria', DZ: 'Algeria', MK: 'Macedonia', UY: 'Uruguay', YT: 'Mayotte',
+               MU: 'Mauritius', TZ: 'Tanzania', LC: 'Saint Lucia', LA: 'Laos', TV: 'Tuval', TW: 'Taiwan',
+               TT: 'Trinidad And Tobago', TR: 'Turkey', LK: 'Sri Lanka', LI: 'Liechtenstein', LV: 'Latvia',
+               TO: 'Tonga', TL: 'Timor-leste', LU: 'Luxembourg', LR: 'Liberia', TK: 'Tokela', TH: 'Thailand',
+               TF: 'French Southern Lands', TG: 'Togo', TD: 'Chad', TC: 'Turks And Caicos Islands', LY: 'Libya',
+               VA: 'Vatican City', AC: 'Ascension Island', VC: 'Saint Vincent And The Grenadines',
+               AE: 'United Arab Emirates', VE: 'Venezuela', AG: 'Antigua And Barbuda', AF: 'Afghanistan', IQ: 'Iraq',
+               VI: 'Virgin Islands, U.s.', IS: 'Iceland', IR: 'Iran', AM: 'Armenia', AL: 'Albania', VN: 'Vietnam',
+               AN: 'Netherlands Antilles', AQ: 'Antarctica', AS: 'American Samoa', AR: 'Argentina', AU: 'Australia',
+               VU: 'Vanuat', IO: 'British Indian Ocean Territory', IN: 'India', LB: 'Lebanon', AZ: 'Azerbaijan',
+               IE: 'Ireland', ID: 'Indonesia', PA: 'Panama', UA: 'Ukraine', QA: 'Qatar', MZ: 'Mozambique'}
+
+end

data/lib/pipl/containers.rb

@@ -0,0 +1,289 @@
+require_relative 'fields'
+require_relative 'utils'
+
+
+module Pipl
+
+  class FieldsContainer
+
+    CLASS_CONTAINER = {
+        Name: 'names',
+        Address: 'addresses',
+        Phone: 'phones',
+        Email: 'emails',
+        Job: 'jobs',
+        Education: 'educations',
+        Image: 'images',
+        Username: 'usernames',
+        UserID: 'user_ids',
+        Url: 'urls',
+        Ethnicity: 'ethnicities',
+        Language: 'languages',
+        OriginCountry: 'origin_countries',
+        Relationship: 'relationships',
+        Tag: 'tags',
+    }
+
+    attr_reader :names, :addresses, :phones, :emails, :jobs, :educations, :images, :usernames, :user_ids, :urls
+    attr_reader :relationships, :tags, :ethnicities, :languages, :origin_countries, :dob, :gender
+
+    def initialize(params={})
+      @names = []
+      @addresses = []
+      @phones = []
+      @emails = []
+      @jobs = []
+      @educations = []
+      @images = []
+      @usernames = []
+      @user_ids = []
+      @urls = []
+      @ethnicities = []
+      @languages = []
+      @origin_countries = []
+      @relationships = []
+      @tags = []
+      @dob = nil
+      @gender = nil
+
+      add_fields params[:fields] if params.key? :fields
+    end
+
+    def self.from_hash(h)
+      raise AbstractMethodInvoked.new
+    end
+
+    def self.fields_from_hash(h)
+      fields = self::CLASS_CONTAINER.map do |cls_name, container|
+        cls = Pipl.const_get cls_name
+        h[container.to_sym].map { |x| cls.from_hash(x) } if h.key? container.to_sym
+      end
+                   .flatten.compact
+      fields << DOB.from_hash(h[:dob]) if h.key? :dob
+      fields << Gender.from_hash(h[:gender]) if h.key? :gender
+      fields
+    end
+
+    def fields_to_hash
+      h = {}
+      h[:dob] = @dob.to_hash if @dob
+      h[:gender] = @gender.to_hash if @gender
+      self.class::CLASS_CONTAINER.values.each do |container|
+        fields = instance_variable_get("@#{container}")
+        h[container.to_sym] = fields.map { |field| field.to_hash }.compact unless fields.empty?
+      end
+      h.reject { |_, value| value.nil? or (value.kind_of?(Array) and value.empty?) }
+    end
+
+    def add_fields(fields)
+      fields.each { |f| add_field f }
+    end
+
+    def add_field(field)
+      cls_sym = field.class.name.split('::').last.to_sym
+      container = self.class::CLASS_CONTAINER[cls_sym]
+      if container
+        instance_variable_get("@#{container}") << field
+      elsif cls_sym == :DOB
+        @dob = field
+      elsif cls_sym == :Gender
+        @gender = field
+      else
+        raise ArgumentError.new("Object of type #{field.class} is an invalid field")
+      end
+    end
+
+    def all_fields
+      fields = self.class::CLASS_CONTAINER.values.map { |container| instance_variable_get("@#{container}") }
+                   .flatten.compact
+      fields << @dob if @dob
+      fields << @gender if @gender
+      fields
+    end
+
+    def job
+      @jobs.first unless @jobs.empty?
+    end
+
+    def address
+      @addresses.first unless @addresses.empty?
+    end
+
+    def education
+      @educations.first unless @educations.empty?
+    end
+
+    def language
+      @languages.first unless @languages.empty?
+    end
+
+    def ethnicity
+      @ethnicities.first unless @ethnicities.empty?
+    end
+
+    def origin_country
+      @origin_countries.first unless @origin_countries.empty?
+    end
+
+    def phone
+      @phones.first unless @phones.empty?
+    end
+
+    def email
+      @emails.first unless @emails.empty?
+    end
+
+    def name
+      @names.first unless @names.empty?
+    end
+
+    def image
+      @images.first unless @images.empty?
+    end
+
+    def url
+      @urls.first unless @urls.empty?
+    end
+
+    def username
+      @usernames.first unless @usernames.empty?
+    end
+
+    def user_id
+      @user_ids.first unless @user_ids.empty?
+    end
+
+    def relationship
+      @relationships.first unless @relationships.empty?
+    end
+
+  end
+
+
+  class Relationship < FieldsContainer
+
+    CLASS_CONTAINER = FieldsContainer::CLASS_CONTAINER.clone
+    CLASS_CONTAINER.delete :Relationship
+
+    # @!attribute valid_since
+    #   @see Field
+    # @!attribute inferred
+    #   @see Field
+    # @!attribute type
+    #   @return [String] Type of association of this relationship to a person.
+    #   Possible values are:
+    #     friend
+    #     family
+    #     work
+    #     other
+    # @!attribute subtype
+    #   @return [String] Subtype of association of this relationship to a person. Free text.
+
+    attr_accessor :valid_since, :inferred, :type, :subtype
+
+    def initialize(params={})
+      super params
+      @valid_since = params[:valid_since]
+      @inferred = params[:inferred]
+      @type = params[:type]
+      @subtype = params[:subtype]
+    end
+
+    def self.from_hash(h)
+      params = Pipl::Field.base_params_from_hash h
+      params[:subtype] = h[:@subtype]
+      params[:fields] = self.fields_from_hash(h)
+      self.new(params)
+    end
+
+    def to_hash
+      fields_to_hash
+    end
+
+    def to_s
+      @names.first.to_s unless @names.empty?
+    end
+
+  end
+
+
+  class Source < FieldsContainer
+
+    attr_reader :match, :name, :category, :origin_url, :sponsored, :domain, :source_id, :person_id, :premium, :valid_since
+
+    def initialize(params={})
+      super params
+      @name = params[:name]
+      @category = params[:category]
+      @origin_url = params[:origin_url]
+      @domain = params[:domain]
+      @source_id = params[:source_id]
+      @person_id = params[:person_id]
+      @sponsored = params[:sponsored]
+      @premium = params[:premium]
+      @match = params[:match]
+      @valid_since = params[:valid_since]
+    end
+
+    def self.from_hash(h)
+      params = {
+          name: h[:@name],
+          category: h[:@category],
+          origin_url: h[:@origin_url],
+          domain: h[:@domain],
+          source_id: h[:@source_id],
+          person_id: h[:@person_id],
+          match: h[:@match],
+          sponsored: h[:@sponsored],
+          premium: h[:@premium],
+      }
+      params[:valid_since] = Pipl::Utils.str_to_date(h[:@valid_since]) if h.key? :@valid_since
+      params[:fields] = self.fields_from_hash(h)
+      self.new(params)
+    end
+
+  end
+
+  class Person < FieldsContainer
+
+    attr_reader :id, :match, :search_pointer
+
+    def initialize(params={})
+      super params
+      @id = params[:id]
+      @match = params[:match]
+      @search_pointer = params[:search_pointer]
+    end
+
+    def self.from_hash(h)
+      params = {
+          id: h[:@id],
+          match: h[:@match],
+          search_pointer: h[:@search_pointer],
+      }
+      params[:fields] = fields_from_hash(h)
+      self.new(params)
+    end
+
+    def to_hash
+      h = {}
+      h[:search_pointer] = @search_pointer if @search_pointer and not @search_pointer.empty?
+      h.update(fields_to_hash)
+      h
+    end
+
+    def is_searchable?
+      not @search_pointer.nil? or
+          @names.any? { |f| f.is_searchable? } or
+          @emails.any? { |f| f.is_searchable? } or
+          @phones.any? { |f| f.is_searchable? } or
+          @usernames.any? { |f| f.is_searchable? }
+    end
+
+    def unsearchable_fields
+      all_fields.reject { |f| f.is_searchable? }
+    end
+
+  end
+
+end