whos_got_dirt 0.0.2

data/lib/whos_got_dirt/requests/entity/open_corporates.rb

@@ -0,0 +1,104 @@
+module WhosGotDirt
+  module Requests
+    module Entity
+      # Requests for companies from the OpenCorporates API.
+      #
+      # OpenCorporates' `fields` and `order` parameters are not supported.
+      #
+      # @example Supply an API key.
+      #   "open_corporates_api_key": "..."
+      #
+      # @example Find companies by name prefix.
+      #   "name~=" "ACME*"
+      #
+      # @example Find companies by jurisdiction code.
+      #   "jurisdiction_code": "gb"
+      #
+      # @example Find companies with one of many jurisdiction codes.
+      #   "jurisdiction_code|=": ["gb", "ie"]
+      #
+      # @example Find companies by country code.
+      #   "country_code": "gb"
+      #
+      # @example Find companies with one of many country codes.
+      #   "country_code|=": ["gb", "ie"]
+      #
+      # @example Find companies by status.
+      #   "current_status": "Dissolved"
+      #
+      # @example Find companies by industry code.
+      #   "industry_code": "be_nace_2008-66191"
+      #
+      # @example Find companies with all the given country codes.
+      #   "a:industry_code": "be_nace_2008-66191",
+      #   "b:industry_code": "be_nace_2008-66199"
+      #
+      # @example Find companies with one of many country codes.
+      #   "industry_code|=": ["be_nace_2008-66191", "be_nace_2008-66199"]
+      #
+      # @example Find active companies (`true` for inactive).
+      #   "inactive": false
+      #
+      # @example Find branch companies (`false` for non-branch).
+      #   "branch": true
+      #
+      # @example Find nonprofit companies (`false` for others).
+      #   "nonprofit": true
+      class OpenCorporates < Request
+        @base_url = 'https://api.opencorporates.com/companies/search'
+
+        # Returns the URL to request.
+        #
+        # @return [String] the URL to request
+        def to_s
+          "#{base_url}?#{to_query(convert.merge(order: 'score'))}"
+        end
+
+        # Returns the "AND" operator's serialization.
+        #
+        # @return [String] the "AND" operator's serialization
+        def and_operator
+          ','
+        end
+
+        # Returns the "OR" operator's serialization.
+        #
+        # @return [String] the "OR" operator's serialization
+        def or_operator
+          '|'
+        end
+
+        # Converts the MQL parameters to API-specific parameters.
+        #
+        # @return [Hash] API-specific parameters
+        # @see https://api.opencorporates.com/documentation/API-Reference
+        def convert
+          match('q', 'name')
+          equal('company_type', 'classification')
+          equal('created_since', 'created_at>=')
+          date_range('incorporation_date', 'founding_date')
+          date_range('dissolution_date', 'dissolution_date')
+          equal('per_page', 'limit', default: input['open_corporates_api_key'] && 100)
+
+          input['contact_details'] && input['contact_details'].each do |contact_detail|
+            if contact_detail['type'] == 'address' && (contact_detail['value'] || contact_detail['value~='])
+              output['registered_address'] = contact_detail['value'] || contact_detail['value~=']
+            end
+          end
+
+          # API-specific parameters.
+          equal('api_token', 'open_corporates_api_key')
+          one_of('jurisdiction_code', 'jurisdiction_code', transform: lambda{|v| v.downcase})
+          one_of('country_code', 'country_code', transform: lambda{|v| v.downcase})
+          equal('current_status', 'current_status')
+          all_of('industry_codes', 'industry_code', backup: :one_of)
+          equal('inactive', 'inactive', valid: [true, false])
+          equal('branch', 'branch', valid: [true, false])
+          equal('nonprofit', 'nonprofit', valid: [true, false])
+
+          output
+        end
+      end
+    end
+  end
+end

data/lib/whos_got_dirt/requests/entity/open_duka.rb

@@ -0,0 +1,33 @@
+module WhosGotDirt
+  module Requests
+    module Entity
+      # Requests for entities from the OpenDuka API.
+      #
+      # @example Supply an API key.
+      #   "open_duka_api_key": "..."
+      class OpenDuka < Request
+        @base_url = 'http://www.openduka.org/index.php/api/search'
+
+        # Returns the URL to request.
+        #
+        # @return [String] the URL to request
+        def to_s
+          "#{base_url}?#{to_query(convert)}"
+        end
+
+        # Converts the MQL parameters to API-specific parameters.
+        #
+        # @return [Hash] API-specific parameters
+        # @see http://www.openduka.org/index.php/api/documentation
+        def convert
+          match('term', 'name')
+
+          # API-specific parameters.
+          equal('key', 'open_duka_api_key')
+
+          output
+        end
+      end
+    end
+  end
+end

data/lib/whos_got_dirt/requests/entity/poderopedia.rb

@@ -0,0 +1,48 @@
+module WhosGotDirt
+  module Requests
+    module Entity
+      # Requests for entities from the Poderopedia API.
+      #
+      # The Poderopedia API returns 10 results only, without pagination.
+      #
+      # The `entity` filter is required.
+      #
+      # @example Supply an API key.
+      #   "poderopedia_api_key": "..."
+      #
+      # @example Find entities of the class `Person` or `Organization`.
+      #   "entity": "Person"
+      class Poderopedia < Request
+        @base_url = 'http://api.poderopedia.org/visualizacion/search'
+
+        # Returns the URL to request.
+        #
+        # @return [String] the URL to request
+        def to_s
+          "#{base_url}?#{to_query(convert)}"
+        end
+
+        # Converts the MQL parameters to API-specific parameters.
+        #
+        # @return [Hash] API-specific parameters
+        # @see http://api.poderopedia.org/search
+        def convert
+          match('alias', 'name')
+
+          # API-specific parameters.
+          equal('user_key', 'poderopedia_api_key')
+          equal('entity', 'type', valid: ['Person', 'Organization'], transform: lambda{|v|
+            case v
+            when 'persona'
+              'Person'
+            when 'organizacion'
+              'Organization'
+            end
+          })
+
+          output
+        end
+      end
+    end
+  end
+end

data/lib/whos_got_dirt/requests/entity.rb

@@ -0,0 +1,54 @@
+module WhosGotDirt
+  module Requests
+    # Requests for entities.
+    #
+    # Many APIs support the parameters below. For API-specific parameters, visit
+    # the API's request class.
+    #
+    # You may filter `dissolution_date` the same as `founding_date`.
+    #
+    # @example Find entities by name (fuzzy match).
+    #   "name~=": "ACME Inc."
+    #
+    # @example Find entities by classification.
+    #   "classification": "Private Limited Company"
+    #
+    # @example Find entities with one of many classifications.
+    #   "classification|=": "Private Limited Company"
+    #
+    # @example Find entities with a creation date greater than or equal to a given value.
+    #   "created_at>=": "2010-01-01"
+    #
+    # @example Find organizations by founding date.
+    #   "founding_date": "2010-01-01"
+    #
+    # @example Find organizations with a founding date greater than or equal to a given value.
+    #   "founding_date>=": "2010-01-03"
+    #
+    # @example Find organizations with a founding date greater than a given value.
+    #   "founding_date>": "2010-01-02"
+    #
+    # @example Find organizations with a founding date less than or equal to a given value.
+    #   "founding_date<=": "2010-01-04"
+    #
+    # @example Find organizations with a founding date less than a given value.
+    #   "founding_date<": "2010-01-05"
+    #
+    # @example Find entities by identifier.
+    #   "identifiers": [{
+    #     "identifier": "911653725",
+    #     "scheme": "IRS Employer Identification Number"
+    #   }]
+    #
+    # @example Find entities by address (fuzzy match).
+    #   "contact_details": [{
+    #     "type": "address",
+    #     "value~=": "52 London"
+    #   }]
+    #
+    # @example Limit the number of results.
+    #   "limit": 5
+    module Entity
+    end
+  end
+end

data/lib/whos_got_dirt/requests/list/little_sis.rb

@@ -0,0 +1,37 @@
+module WhosGotDirt
+  module Requests
+    module List
+      # Requests for lists from the LittleSis API.
+      #
+      # The `q` parameter matches names and descriptions.
+      #
+      # @example Supply an API key.
+      #   "little_sis_api_key": "..."
+      class LittleSis < Request
+        # The JSON response has less metadata, e.g. number of results.
+        @base_url = 'https://api.littlesis.org/lists.xml'
+
+        # Returns the URL to request.
+        #
+        # @return [String] the URL to request
+        def to_s
+          "#{base_url}?#{to_query(convert)}"
+        end
+
+        # Converts the MQL parameters to API-specific parameters.
+        #
+        # @return [Hash] API-specific parameters
+        # @see http://api.littlesis.org/documentation#lists
+        def convert
+          match('q', 'name')
+          equal('num', 'limit')
+
+          # API-specific parameters.
+          equal('_key', 'little_sis_api_key')
+
+          output
+        end
+      end
+    end
+  end
+end

data/lib/whos_got_dirt/requests/list/open_corporates.rb

@@ -0,0 +1,36 @@
+module WhosGotDirt
+  module Requests
+    module List
+      # Requests for corporate groupings from the OpenCorporates API.
+      #
+      # OpenCorporates' `q` filter performs a prefix search.
+      #
+      # @example Supply an API key.
+      #   "open_corporates_api_key": "..."
+      class OpenCorporates < Request
+        @base_url = 'https://api.opencorporates.com/corporate_groupings/search'
+
+        # Returns the URL to request.
+        #
+        # @return [String] the URL to request
+        def to_s
+          "#{base_url}?#{to_query(convert)}"
+        end
+
+        # Converts the MQL parameters to API-specific parameters.
+        #
+        # @return [Hash] API-specific parameters
+        # @see https://api.opencorporates.com/documentation/API-Reference
+        def convert
+          match('q', 'name')
+          equal('per_page', 'limit', default: input['open_corporates_api_key'] && 100)
+
+          # API-specific parameters.
+          equal('api_token', 'open_corporates_api_key')
+
+          output
+        end
+      end
+    end
+  end
+end

data/lib/whos_got_dirt/requests/list.rb

@@ -0,0 +1,16 @@
+module WhosGotDirt
+  module Requests
+    # Requests for lists.
+    #
+    # Many APIs support the parameters below. For API-specific parameters, visit
+    # the API's request class.
+    #
+    # @example Find lists by name (fuzzy match).
+    #   "name~=": "Barclays"
+    #
+    # @example Limit the number of results.
+    #   "limit": 5
+    module List
+    end
+  end
+end

data/lib/whos_got_dirt/requests/relation/open_corporates.rb

@@ -0,0 +1,72 @@
+module WhosGotDirt
+  module Requests
+    module Relation
+      # Requests for corporate officerships from the OpenCorporates API.
+      #
+      # OpenCorporates' `date_of_birth` and `address` filters require an API
+      # key. Its `order` parameter is not supported.
+      #
+      # @example Supply an API key.
+      #   "open_corporates_api_key": "..."
+      #
+      # @example Find officerships by jurisdiction code.
+      #   "jurisdiction_code": "gb"
+      #
+      # @example Find officerships with one of many jurisdiction codes.
+      #   "jurisdiction_code|=": ["gb", "ie"]
+      #
+      # @example Find officerships by role.
+      #   "role": "ceo"
+      #
+      # @example Find active officerships.
+      #   "inactive": false
+      #
+      # @example Find inactive officerships.
+      #   "inactive": true
+      class OpenCorporates < Request
+        @base_url = 'https://api.opencorporates.com/officers/search'
+
+        # Returns the URL to request.
+        #
+        # @return [String] the URL to request
+        def to_s
+          "#{base_url}?#{to_query(convert.merge(order: 'score'))}"
+        end
+
+        # Returns the "OR" operator's serialization.
+        #
+        # @return [String] the "OR" operator's serialization
+        def or_operator
+          '|'
+        end
+
+        # Converts the MQL parameters to API-specific parameters.
+        #
+        # @return [Hash] API-specific parameters
+        # @see https://api.opencorporates.com/documentation/API-Reference
+        def convert
+          equal('per_page', 'limit', default: input['open_corporates_api_key'] && 100)
+
+          input['subject'] && input['subject'].each do |subject|
+            match('q', 'name', input: subject)
+            date_range('date_of_birth', 'birth_date', input: subject)
+
+            subject['contact_details'] && subject['contact_details'].each do |contact_detail|
+              if contact_detail['type'] == 'address' && (contact_detail['value'] || contact_detail['value~='])
+                output['address'] = contact_detail['value'] || contact_detail['value~=']
+              end
+            end
+          end
+
+          # API-specific parameters.
+          equal('api_token', 'open_corporates_api_key')
+          one_of('jurisdiction_code', 'jurisdiction_code', transform: lambda{|v| v.downcase})
+          equal('position', 'role')
+          equal('inactive', 'inactive', valid: [true, false])
+
+          output
+        end
+      end
+    end
+  end
+end

data/lib/whos_got_dirt/requests/relation/open_oil.rb

@@ -0,0 +1,49 @@
+module WhosGotDirt
+  module Requests
+    module Relation
+      # Requests for concessions from the OpenOil API.
+      #
+      # @example Supply an API key.
+      #   "open_oil_api_key": "..."
+      #
+      # @example Find concessions by country code.
+      #   "country_code": "BR"
+      #
+      # @example Find concessions with a "licensed" or "unlicensed" status.
+      #   "status": "licensed"
+      #
+      # @example Find concessions with an "offshore" or "onshore" type.
+      #   "type": "offshore"
+      class OpenOil < Request
+        @base_url = 'https://api.openoil.net/concession/search'
+
+        # Returns the URL to request.
+        #
+        # @return [String] the URL to request
+        def to_s
+          "#{base_url}?#{to_query(convert)}"
+        end
+
+        # Converts the MQL parameters to API-specific parameters.
+        #
+        # @return [Hash] API-specific parameters
+        # @see http://openoil.net/openoil-api/
+        def convert
+          equal('per_page', 'limit')
+
+          input['subject'] && input['subject'].each do |subject|
+            equal('licensee', 'name', input: subject) # doesn't work, upstream bug
+          end
+
+          # API-specific parameters.
+          equal('apikey', 'open_oil_api_key')
+          equal('country', 'country_code', transform: lambda{|v| v.upcase})
+          equal('status', 'status', valid: ['licensed', 'unlicensed'])
+          equal('type', 'type', valid: ['offshore', 'onshore'])
+
+          output
+        end
+      end
+    end
+  end
+end

data/lib/whos_got_dirt/requests/relation.rb

@@ -0,0 +1,51 @@
+module WhosGotDirt
+  module Requests
+    # Requests for relations.
+    #
+    # Many APIs support the parameters below. For API-specific parameters, visit
+    # the API's request class.
+    #
+    # @example Find related entities by name (fuzzy match).
+    #   "subject": [{
+    #     "name~=": "John Smith"
+    #   }]
+    #
+    # @example Find related people by birth date.
+    #   "subject": [{
+    #     "birth_date": "2010-01-01"
+    #   }]
+    #
+    # @example Find related people with a birth date greater than or equal to a given value.
+    #   "subject": [{
+    #     "birth_date>=": "2010-01-03"
+    #   }]
+    #
+    # @example Find related people with a birth date greater than a given value.
+    #   "subject": [{
+    #     "birth_date>": "2010-01-02"
+    #   }]
+    #
+    # @example Find related people with a birth date less than or equal to a given value.
+    #   "subject": [{
+    #     "birth_date<=": "2010-01-04"
+    #   }]
+    #
+    # @example Find related people with a birth date less than a given value.
+    #   "subject": [{
+    #     "birth_date<": "2010-01-05"
+    #   }]
+    #
+    # @example Find related entities by address (fuzzy match).
+    #   "subject": [{
+    #     "contact_details": [{
+    #       "type": "address",
+    #       "value~=": "52 London"
+    #     }]
+    #   }]
+    #
+    # @example Limit the number of results.
+    #   "limit": 5
+    module Relation
+    end
+  end
+end

data/lib/whos_got_dirt/response.rb

@@ -0,0 +1,79 @@
+module WhosGotDirt
+  # Accepts a response and returns the results in a consistent format.
+  #
+  # @example Create a new class for transforming responses to results.
+  #   class MyAPIResponse < WhosGotDirt::Response
+  #     def to_a
+  #       JSON.load(body).map do |result|
+  #         {
+  #           request_url: env.url.to_s,
+  #           name: result['Name'],
+  #         }
+  #       end
+  #     end
+  #   end
+  #
+  # @example Use the class to parse a response.
+  #   url = MyAPIRequest.new(name: 'John Smith').to_s
+  #   response = Faraday.get(url)
+  #   MyAPIResponse.new(response).to_a
+  #   # [{
+  #   #   :request_url=>"https://api.example.com/endpoint?name=John+Smith",
+  #   #   :name=>"John Smith"
+  #   # }, {
+  #   #   :request_url=>"https://api.example.com/endpoint?name=John+Smith",
+  #   #   :name=>"John Aaron Smith"
+  #   # }]
+  class Response < SimpleDelegator
+    class << self
+      # @!attribute [r] template
+      #   @return [Hash] the result template
+      attr_reader :template
+    end
+
+    # Returns the result renderer.
+    #
+    # @return the result renderer
+    def renderer
+      @renderer ||= Renderer.new(self.class.template)
+    end
+
+    # Returns the parsed response body.
+    #
+    # @return the parsed response body
+    def parsed_body
+      @parsed_body ||= parse_body
+    end
+
+    # @abstract Subclass and override {#parse_body} to parse the response body
+    def parse_body
+      raise NotImplementedError
+    end
+
+    # @abstract Subclass and override {#to_a} to transform the parsed response
+    #   body into results
+    def to_a
+      raise NotImplementedError
+    end
+
+    # @!method initialize(response)
+    #   Sets the response's response.
+    #   @param [Faraday::Response] response a response
+
+    # @!method body
+    #   Returns the response body.
+    #   @return [String] the response body
+
+    # @!method env
+    #   Returns the response's internals.
+    #   @return [#url,#request_headers] the response's internals
+
+    # @!method headers
+    #   Returns the response headers.
+    #   @return [#[]] the response headers
+
+    # @!method status
+    #   Returns the HTTP status code.
+    #   @return [Fixnum] the HTTP status code
+  end
+end

data/lib/whos_got_dirt/responses/entity/corp_watch.rb

@@ -0,0 +1,72 @@
+module WhosGotDirt
+  module Responses
+    module Entity
+      # Converts entities from the CorpWatch API to Popolo format.
+      #
+      # @see http://api.corpwatch.org/documentation/api_examples.html#A17
+      class CorpWatch < Response
+        @template = {
+          '@type' => 'Entity',
+          'name' => '/company_name',
+          'identifiers' => [{
+            'identifier' => '/cw_id',
+            'scheme' => 'CorpWatch',
+          }, {
+            'identifier' => '/irs_number',
+            'scheme' => 'IRS Employer Identification Number',
+          }, {
+            'identifier' => '/cik',
+            'scheme' => 'SEC Central Index Key',
+          }],
+          'contact_details' => [{
+            'type' => 'address',
+            'value' => '/raw_address',
+          }],
+          # API-specific.
+          'industry_code' => '/sic_code',
+          'industry_name' => '/industry_name',
+          'sector_code' => '/sic_sector',
+          'sector_name' => '/sector_name',
+          'country_code' => '/country_code',
+          'subdiv_code' => '/subdiv_code',
+          'min_year' => '/min_year',
+          'max_year' => '/max_year',
+          'source_type' => '/source_type',
+          'num_parents' => '/num_parents',
+          'num_children' => '/num_children',
+          'top_parent_id' => '/top_parent_id',
+        }
+
+        # Parses the response body.
+        #
+        # @return [Array<Hash>] the parsed response body
+        def parse_body
+          JSON.load(body)
+        end
+
+        # Returns the total number of matching results.
+        #
+        # @return [Fixnum] the total number of matching results
+        def count
+          Integer(parsed_body['meta']['total_results'])
+        end
+
+        # Returns the current index.
+        #
+        # @return [Fixnum] the current index
+        def index
+          parsed_body['meta']['parameters']['index']
+        end
+
+        # Transforms the parsed response body into results.
+        #
+        # @return [Array<Hash>] the results
+        def to_a
+          parsed_body['result'].map do |data|
+            Result.new('Entity', renderer.result(data), self).finalize!
+          end
+        end
+      end
+    end
+  end
+end