whos_got_dirt 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 98d4adb0f91ffac1ff9ceabe8232a3861e2f900a
+  data.tar.gz: 627276f14cba96da225df90590eb71267ef13c1a
+SHA512:
+  metadata.gz: d9e8cdc8e2076c071af133ac8abdcf97d0676c4edf6712c9591ab661ade771f5729abde4cef9766834fb49c282e6a6f1b134ab7daed572aaa55a9427b912184c
+  data.tar.gz: 1ff4a4d9c4afb312c5550afb83c48b503ecb82186fcb106240b6db7ca05187458d9fe067f1cef806e5c6f02841692150e0fb88ea21194e2560ed37f4b0010b89

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+.bundle
+.yardoc
+Gemfile.lock
+doc/*
+pkg/*

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,20 @@
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+  - 2.2.0
+env:
+  global:
+    # CORP_WATCH_API_KEY
+    - secure: dLqYYE/SMgjM7t4760RyWo9JC5gyGQ4QeBFDiiznEV1th1YQjXgBZxAKzwH2msjOL93z1F9U0AGmkSwm7uX6y6l6/Oom4zyjSJv2j/GTsNCB6dKLSKLDjL01Veb9+HjLtOgp/b8cCptzs/V0k79So3ku8MPGkZR8xOTu3C+8tjQEolUFIPTAxPTYYQAz2EirUgxlvXKTPXT6cSJMFoq5LOpzMhFpRwcAL5C0dg7WLObESCqZr8ZBPmAGMFbzI9toktDPFbgp6M7MpF/9qfU3PJNnGISp3T6/YQRXOcOacKrznE8BH6LKDApA02kB2u4YeBLpkM10APwi5/4leYEB1AY+LrVrCzyWibtIDLRYJfwuiiX8rd9w1aIhFs0WEnnvcSpb/sbW6PPuc9f3p6z+AqGek5fg3UhLGJPwP9Yz6eY34bwe+pD2JwL/iksORawHhtiyP3VXsaxIQnQTV/A3qv/mTkMPsTltgtBVLZobxkgz+QTcqaZPin82EnyaD4RKAYF8pfBidGStiG/hsBkMM6vnkF0usKAR6r9A7aZdRDs9v4E1A/RY0weonJPD3caOKX5rQm5rTrd8oS8J1bMyMKDNuOo0rvpPGM0KmZ/ePRFLN4Soo0EDFmGSoZjam8QI9EN2Gu7OlcvjrT3vRp4E5KbLtRGt/kZD+Z2u23ttRg0=
+    # LITTLE_SIS_API_KEY
+    - secure: P+76fE58oTzuM+1EVJI8WhzqE8QxxgyxOhtiAudTNt6tPA7VuQvbSbe8MAkiOvSnWQ/wAiJkhGZLE93lKSjOuBTLBbCcwLtMMQ+6U/WkLSVPUxD2p+HgMynZaV1zBbGbrBpOnTj4WyeM1Jz+zJkrI5YCOO1XS39mUNn9RZh6Bepg3mzRlRmsAy47bgzhprbv21tWmR9C2LZvhzSfWu+2GCKCVrnGdBDQ1WoKhnwCEboxdjDb0sdD/GlmebLMMfiS1MRpoXw0Z4AdLm2/eBAI4t/USeGLMan23U53BZ2yBAhy5Ns42+f18zr1iOHoX05oyevlqJkKEdEhnoJ1CyxByKQVLe0oWIgW38SgWvTTl+JaSSPyiNxlK6Asr3VKcMfui+nKziHfMSZTtwm9lq6JzSaOM2L/+Qe90BHN0raWH2uvR3ACCmR/PP7tl7ZV+8nNQ4nmzt2H9DpQEnYsil/4eQ3hLrny9fTMylYJpiN1yNhaVnWMXw2hknBnUwBq42Xu3zsv1dMYGzi1C/nJWw/3imIvftiJxArOlSFcZ+dB3iBWou5sm9pJpRtUyLcwhah6zc+GEroMdv6d27r8ANabtOAMgjxR29lFpNThMBgO84DWD05CViyzCBZQf8eNWvVRrmjAC+wn8L71ZSqOgauH7Urw0qJda2uvLZ7biJBCnvs=
+    # OPEN_DUKA_API_KEY
+    - secure: CYftDtbj2dqO0YQpct+r1SKkqKGbUeQCo4O0muBLQb6l87C9kCCKfNbgfMWzpuoFQXWD0CYRQvt22S8ulQl5pA6RYV0L0pAhiijRNWs090+1aEnqbmSWz0thhrdX7YGjiaEmd8KN7iCygDGxMV/az57LhqfETKQOJdI9Q0Ozynw5LuawW1kUsrzA6wy0uWxIz9g4Whtqh3ZGFgkJjFkMff2z5ZP4XRljNjxs6h/AFGiKWKOYtGTGI4JmlbZu5ibfqZ9G+ipS3Sg5tOVWjU43hUXmrMgbXNXB2Q/mkLpxDqRYLFfyj6KWTNaeVwqbURagswZ3u57ZhntUGsqL8tB8wVwM8WbVCx9neY1RRvSIl9Rhiobe4L1qEGxG9nEVHLlAh7S6JEt/iekzkribJnwdk2IaTdJ4rjkaaYLoYW59TLsMnTAxSoEjvPRU8E0WPrlHu1xYBW0/JieuoJVPXOD+z6wAMKM7BjswtRNmCmQ53C6M8AJvgg/HbKqA+5INBQomnyHZape3aCk7DX8FnL6DuBsYNFonMFN+IjfL/eP9gx9l1rY6hmyYVCIbqZ91OTdvMHDdJsYVkBMXX9Xrp6zQQDVapo4FArWji8BRfZwyOeplmUqx4ERP99+RKgVC5mRXqygGTRzYd6rHfThPZNQNQvzrrwIohEPWC4E6u2OKi1s=
+    # OPEN_OIL_API_KEY
+    - secure: bdGjQmbZ6oYVaM/UEqyGK6fZF/LTJLqWdmzP+HpVax5c6ogsTKhcruTScmkH4IbZRD3UCRc8WAh0Y4Wcr2xoxWwcdJS0XY2QQfsENrc8k0GMBr8ijf8nrSLwon1hUdxhmvFRpsDBIU7N2qhAvcYUVvFGKp8e1FsNzxFJZRsHC2cY1UxQyiWKMkLaGgdhki56/CJefH4TRuNFkuEIYyGiOiQX+QdtX9PhIYF1ycu2ucAF1qUBh9fMLyLv8YH+Hiudy8ko8SmHskhOTHtqvD542dbSzYznrvdVo+K1+4TcBajZ7jR8smoqvIzMxUpJXjLv/UpPmz0YIor8EeVSiKslXmCcpM5b5KVT+aAkMxk/0RTOEDJ1G8MuCwypUo9CiSqtg5quaOPRK4Yu4fsqGAO7oYD1rfyZj1b1lSy91yuS55ZlIsskJhDBLk4UEcugjtqjy4d0/JDfl97WmMX9QqvLw4K9vbSp+uBAIJbulvelB5ya1VaE7k2eGxiw4T5AommhltXvn64tahMf609bc42LiV8+FsW/LO/1GPQbHIM2ojQ24Rq3SdaMQxXnJTILFyQQX672ECAf/ME9QRwY3S7T9SoKEvWeB92Flo9NzFX+wodHME+yn0av5Em8st0MaBNJlHFrc2zAYKaSIdSpvW2c+15Ip3UEBQ/YKsu8ydouVTk=
+    # PODEROPEDIA_API_KEY
+    - secure: AfDhdNDjaio3W804DXKAaL6hyThHjM5670eZSF/2kKExyI1mxGSjS7uuB8102zhh8mRyZzs1iYr2SeWUvTeOCtbIo2Vo6apctQQnVjUGJ0WGWYCJD1Y+9sWknw3PxTq1ca8x9B3/jMJeppFJpJglqI+yYWrWYS5jXJ68H6BsNXK8zTJCuGQF62dxYds36r2CLVQmvs27zqox2HpwAJQ3dzS5aM+SxOQv3TemqjhHJ+nJ3F3dISQytEfBkSXIdyEdN8tT3QkppDbMfTilAuvezdI5QuY0kxWcrQXDBCSByaKb2PAxC5JXa3MBO/EiqZ8WAv1MDfJW/0DhfJTE0+Iznm2IUBY7hLMo2up046KnkfTygBTu25F6B5eFz5geqJH4RIf0bqtxwIp1h0cVOtV3QoWILDjl88dOqMuoUNiE/36ikwkesqXGbtLKrpqCgJm2f/HDWMtLjzcsdYiyzoGsoC4yoUPQNMHis/R0uRSGTx1BEFXL0RBYOCwrztWl4OPDfQUwuLHBp+5gcGCzz1RBeuBmQHqZ2amhxSMwSzl1ehME4yF2t6Rm50ROM1QUYz1ee5fGerSpDjNFyR0aFUBpbPPrSLdIX0UKDU3W1mXVZ+wKvSZAk+5/tS89YCbgwMSl4cJwATG8uBkM/OR/G8hq3qJTP55AfdFOxIeAhXjPT7M=

data/.yardopts

@@ -0,0 +1,3 @@
+--hide-void-return
+--embed-mixin ClassMethods
+--markup=markdown

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in the gemspec
+gemspec
+
+# Remove once vcr 2.9.4 released.
+gem 'vcr', git: 'https://github.com/vcr/vcr.git'

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2015 James McKinney
+
+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,61 @@
+# Who's got dirt? A federated search API for entities and relations
+
+[![Gem Version](https://badge.fury.io/rb/whos_got_dirt.svg)](https://badge.fury.io/rb/whos_got_dirt)
+[![Build Status](https://secure.travis-ci.org/influencemapping/whos_got_dirt-gem.png)](https://travis-ci.org/influencemapping/whos_got_dirt-gem)
+[![Dependency Status](https://gemnasium.com/influencemapping/whos_got_dirt-gem.png)](https://gemnasium.com/influencemapping/whos_got_dirt-gem)
+[![Coverage Status](https://coveralls.io/repos/influencemapping/whos_got_dirt-gem/badge.svg)](https://coveralls.io/r/influencemapping/whos_got_dirt-gem)
+[![Code Climate](https://codeclimate.com/github/influencemapping/whos_got_dirt-gem.png)](https://codeclimate.com/github/influencemapping/whos_got_dirt-gem)
+
+## Usage
+
+This gem provides a common API to multiple APIs. See the [server](https://github.com/influencemapping/whos_got_dirt-server) for a deployment.
+
+To add support for new APIs, see the documentation for [Request](http://www.rubydoc.info/gems/whos_got_dirt/WhosGotDirt/Request) and [Response](http://www.rubydoc.info/gems/whos_got_dirt/WhosGotDirt/Response).
+
+In this example, we convert generic API parameters to an OpenCorporates API URL, and request the URL with [Faraday](https://github.com/lostisland/faraday). Then, we convert the OpenCorporates API response to a generic API response.
+
+```ruby
+require 'whos_got_dirt'
+require 'faraday'
+
+input = {
+  'subject' => [{
+    'name~=' => 'John Smith',
+  }],
+  'jurisdiction_code|=' => ['gb', 'ie'],
+  'role' => 'director',
+  'inactive' => false,
+}
+
+url = WhosGotDirt::Requests::Relation::OpenCorporates.new(input).to_s
+#=> "https://api.opencorporates.com/officers/search?q=John+Smith&jurisdiction_code=gb%7Cie&position=director&inactive=false&order=score"
+
+response = Faraday.get(url)
+
+results = WhosGotDirt::Responses::Relation::OpenCorporates.new(response).to_a
+#=> [{"@type"=>"Relation",
+#  "subject"=>
+#   {"name"=>"JOHN SMITH",
+#    "contact_details"=>[],
+#    "occupation"=>"CONTRACTS DIRECTORS"},
+#  "object"=>
+#   {"name"=>"IMPERIAL DUCTWORK SERVICES HOLDINGS LIMITED",
+#    "identifiers"=>[{"identifier"=>"08484366", "scheme"=>"Company Register"}],
+#    "links"=>[{"url"=>"https://opencorporates.com/companies/gb/08484366", "note"=>"OpenCorporates URL"}],
+#    "jurisdiction_code"=>"gb"},
+#  "start_date"=>"2013-04-30",
+#  "identifiers"=>[{"identifier"=>"71863990", "scheme"=>"OpenCorporates"}],
+#  "links"=>[{"url"=>"https://opencorporates.com/officers/71863990", "note"=>"OpenCorporates URL"}],
+#  "updated_at"=>"2014-10-13T13:57:58+00:00",
+#  "current_status"=>"CURRENT",
+#  "jurisdiction_code"=>"gb",
+#  "role"=>"director",
+#  "sources"=>[{"url"=>"https://api.opencorporates.com/officers/search?inactive=false&jurisdiction_code=gb%7Cie&order=score&position=director&q=John+Smith", "note"=>"OpenCorporates"}]},
+#  ...]
+```
+
+## Acknowledgements
+
+Most terms are from [Popolo](http://www.popoloproject.com/). The request and response formats are inspired from the [Metaweb Query Language](http://mql.freebaseapps.com/index.html) and the [OpenRefine Reconciliation Service API](https://github.com/OpenRefine/OpenRefine/wiki/Reconciliation-Service-API).
+
+Copyright (c) 2015 James McKinney, released under the MIT license

data/Rakefile

@@ -0,0 +1,69 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yard do
+    abort 'YARD is not available. In order to run yard, you must: gem install yard'
+  end
+end
+
+desc 'Fetch schemas, rewrite references, and store locally'
+task :schemas do
+  require 'json'
+  require 'open-uri'
+
+  require 'json-schema'
+
+  def process_value(value, definitions)
+    url = value['$ref']
+    if url
+      name = url.rpartition('/')[2].chomp('.json#')
+      value['$ref'] = "#/definitions/#{name}"
+      define(name, url, definitions)
+    end
+  end
+
+  def process_schema(url, definitions)
+    schema = JSON.load(open(url).read)
+    schema['properties'].each do |_,value|
+      process_value(value, definitions)
+      if value.key?('items')
+        process_value(value['items'], definitions)
+      end
+    end
+    schema
+  end
+
+  def define(name, url, definitions)
+    unless definitions.key?(name)
+      definitions[name] = {} # to avoid recursion
+      definitions[name] = process_schema(url, definitions)
+      definitions[name].delete('id')
+    end
+  end
+
+  definitions = {} # passed by reference
+
+  %w(organization person).each do |name|
+    define(name, "http://www.popoloproject.com/schemas/#{name}.json#", definitions)
+  end
+
+  schema = {
+    '$schema' => 'http://json-schema.org/draft-03/schema#',
+    'definitions' => definitions,
+  }
+
+  JSON::Validator.validate!(schema, {}, validate_schema: true)
+
+  File.open(File.expand_path(File.join('..', 'schemas', 'popolo.json'), __FILE__), 'w') do |f|
+    f.write(JSON.pretty_generate(schema))
+  end
+end

data/lib/whos_got_dirt/renderer.rb

@@ -0,0 +1,66 @@
+module WhosGotDirt
+  # Accepts a JSON template, which is a hash in which some values are
+  # [JSON Pointers](http://tools.ietf.org/html/rfc6901). The template is
+  # rendered by evaluating its JSON Pointers against JSON data.
+  #
+  # @example
+  #   renderer = WhosGotDirt::Renderer.new('name' => '/fn')
+  #   data = {'fn' => 'John Smith'}
+  #   renderer.result(data)
+  #   #=> {'name' => 'John Smith'}
+  #
+  # @see http://ruby-doc.org/stdlib-2.2.3/libdoc/erb/rdoc/ERB.html
+  class Renderer
+    # @!attribute [r] template
+    #   @return [Hash] the template
+    attr_reader :template
+
+    # Sets the template.
+    #
+    # @param [Object] template a template
+    def initialize(template)
+      @template = template
+    end
+
+    # Renders the template by evaluating its JSON Pointers against JSON data.
+    #
+    # @param [Object] data the JSON data
+    # @return [Object] the rendered template
+    def result(data)
+      walk(template, data)
+    end
+
+  private
+
+    # @see https://github.com/pudo/jsonmapping/blob/master/jsonmapping/mapper.py
+    def walk(node, data)
+      case node
+      when Hash
+        hash = {}
+        node.each do |key,value|
+          if value.respond_to?(:call)
+            k, v = value.call(data)
+          else
+            v = walk(value, data)
+          end
+          if v
+            hash[k || key] = v
+          end
+        end
+        hash
+      when Array
+        node.map do |child|
+          walk(child, data)
+        end
+      when String
+        if node.start_with?('/')
+          JsonPointer.new(data, node).value
+        else
+          node
+        end
+      else
+        node
+      end
+    end
+  end
+end

data/lib/whos_got_dirt/request.rb

@@ -0,0 +1,218 @@
+module WhosGotDirt
+  # Accepts MQL parameters and return URLs to request.
+  #
+  # @example Create a new class for transforming parameters to URLs.
+  #   class MyAPIRequest < WhosGotDirt::Request
+  #     @base_url = 'https://api.example.com'
+  #
+  #     def to_s
+  #       "#{base_url}/endpoint?#{to_query(input)}"
+  #     end
+  #   end
+  #
+  # @example Use the class in requesting a URL.
+  #   url = MyAPIRequest.new(name: 'John Smith').to_s
+  #   response = Faraday.get(url)
+  #   #=> "https://api.example.com/endpoint?name=John+Smith"
+  class Request
+    class << self
+      # @!attribute [r] base_url
+      #   @return [String] the base URL to be used in the request
+      attr_reader :base_url
+
+      # Transforms a query string from a hash to a string.
+      #
+      # @param [Hash] params query string parameters
+      # @return [String] a query string
+      def to_query(params)
+        params.map do |key,value|
+          "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
+        end * '&'
+      end
+    end
+
+    # @!attribute input
+    #   @return [Hash] the MQL parameters
+    attr_accessor :input
+
+    # @!attribute :output
+    #   @return [Hash] the API-specific parameters
+    attr_reader :output
+
+    # Sets the MQL parameters.
+    #
+    # @param [Hash] input the MQL parameters
+    def initialize(input = {})
+      @input = ActiveSupport::HashWithIndifferentAccess.new(input)
+      @output = {}
+    end
+
+    # Returns the base URL to be used in the request.
+    #
+    # @return [String] the base URL to be used in the request
+    def base_url
+      self.class.base_url
+    end
+
+    # Helper method to map a parameter that supports the MQL equality operator.
+    #
+    # @param [String] target the API-specific parameter name
+    # @param [String] source the request parameter name
+    # @param [Hash] opts options
+    # @option opts [String] :input substitute MQL parameters
+    # @option opts [String] :transform a transformation to apply to the value
+    # @option opts [String] :default the default value
+    # @option opts [Set,Array] :valid a list of valid values
+    # @return [Hash] the API-specific parameters
+    def equal(target, source, opts = {})
+      params = parameters(opts)
+
+      if opts.key?(:valid)
+        if opts[:valid].include?(params[source])
+          output[target] = transform(params[source], opts)
+        end
+      else
+        if params[source]
+          output[target] = transform(params[source], opts)
+        elsif opts[:default]
+          output[target] = opts[:default]
+        end
+      end
+
+      output
+    end
+
+    # Helper method to map a parameter that supports the MQL `~=` operator.
+    #
+    # @param [String] target the API-specific parameter name
+    # @param [String] source the request parameter name
+    # @param [Hash] opts options
+    # @option opts [String] :input substitute MQL parameters
+    # @option opts [String] :transform a transformation to apply to the value
+    # @return [Hash] the API-specific parameters
+    def match(target, source, opts = {})
+      params = parameters(opts)
+
+      if params[source]
+        equal(target, source, opts)
+      elsif params["#{source}~="]
+        output[target] = transform(params["#{source}~="], opts)
+      end
+
+      output
+    end
+
+    # Helper method to map a parameter that supports the MQL `|=` operator.
+    #
+    # @param [String] target the API-specific parameter name
+    # @param [String] source the request parameter name
+    # @param [Hash] opts options
+    # @option opts [String] :input substitute MQL parameters
+    # @option opts [String] :transform a transformation to apply to the value
+    # @return [Hash] the API-specific parameters
+    def one_of(target, source, opts = {})
+      params = parameters(opts)
+
+      if params[source]
+        equal(target, source, opts)
+      elsif params["#{source}|="]
+        output[target] = params["#{source}|="].map{|v| transform(v, opts)}.join(or_operator)
+      end
+
+      output
+    end
+
+    # Helper method to map a parameter that supports MQL `AND`-like constraints.
+    #
+    # @param [String] target the API-specific parameter name
+    # @param [String] source the request parameter name
+    # @param [Hash] opts options
+    # @option opts [String] :input substitute MQL parameters
+    # @option opts [String] :transform a transformation to apply to the value
+    # @option opts [String] :transform a transformation to apply to the value
+    # @return [Hash] the API-specific parameters
+    def all_of(target, source, opts = {})
+      params = parameters(opts)
+
+      if params[source]
+        equal(target, source, opts)
+      else
+        values = []
+        params.each do |key,value|
+          if key[/:([a-z_]+)$/, 1] == source
+            values << value
+          end
+        end
+        if values.empty?
+          if opts.key?(:backup)
+            send(opts[:backup], target, source, opts)
+          end
+        else
+          output[target] = values.map{|v| transform(v, opts)}.join(and_operator)
+        end
+      end
+
+      output
+    end
+
+    # Helper method to map a date parameter that supports comparisons.
+    #
+    # @param [String] target the API-specific parameter name
+    # @param [String] source the request parameter name
+    # @param [Hash] opts options
+    # @option opts [String] :input substitute MQL parameters
+    # @return [Hash] the API-specific parameters
+    def date_range(target, source, opts = {})
+      params = parameters(opts)
+
+      # @note OpenCorporates date range format.
+      if params[source]
+        output[target] = "#{params[source]}:#{params[source]}"
+      elsif params["#{source}>="] || params["#{source}>"] || params["#{source}<="] || params["#{source}<"]
+        output[target] = "#{params["#{source}>="] || params["#{source}>"]}:#{params["#{source}<="] || params["#{source}<"]}"
+      end
+
+      output
+    end
+
+    # @abstract Subclass and override {#to_s} to return the URL from which to
+    #   `GET` the results
+    def to_s
+      raise NotImplementedError
+    end
+
+    # @abstract Subclass and override {#and_operator} to return the "AND"
+    #   operator's serialization
+    def and_operator
+      raise NotImplementedError
+    end
+
+    # @abstract Subclass and override {#or_operator} to return the "OR"
+    #   operator's serialization
+    def or_operator
+      raise NotImplementedError
+    end
+
+  private
+
+    def to_query(params)
+      self.class.to_query(params)
+    end
+
+    def parameters(opts)
+      if opts.key?(:input)
+        opts[:input]
+      else
+        input
+      end
+    end
+
+    def transform(value, opts)
+      if opts.key?(:transform)
+        opts[:transform].call(value)
+      else
+        value
+      end
+    end
+  end
+end

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

@@ -0,0 +1,123 @@
+module WhosGotDirt
+  module Requests
+    module Entity
+      # Requests for companies from the CorpWatch API.
+      #
+      # By default, name and address queries will match complete words only in
+      # the same order as in the query, tokens less than three characters long
+      # will be ignored, and MySQL's [stopwords](http://dev.mysql.com/doc/refman/5.0/en/fulltext-stopwords.html)
+      # will be ignored. If `substring_match` is `1`, queries will match within
+      # words as well as complete words, at a severe performance penalty.
+      #
+      # @example Supply an API key.
+      #   "corp_watch_api_key": "..."
+      #
+      # @example Find entities by IRS Employer Identification Number (EIN).
+      #   "identifiers": [{
+      #     "identifier": "911653725",
+      #     "scheme": "IRS Employer Identification Number"
+      #   }]
+      #
+      # @example Find entities by SEC Central Index Key (CIK).
+      #   "identifiers": [{
+      #     "identifier": "37996",
+      #     "scheme": "SEC Central Index Key"
+      #   }]
+      #
+      # @example Find companies by SIC code.
+      #   "industry_code": "2011"
+      #
+      # @example Find companies by SIC sector.
+      #   "sector_code": "4100"
+      #
+      # @example Match within words on name and address queries.
+      #   "substring_match": 1
+      #
+      # @example Find companies by country code.
+      #   "country_code": "US"
+      #
+      # @example Find companies by country subdivision code.
+      #   "subdiv_code": "OR"
+      #
+      # @example Find companies with SEC filings in a given year.
+      #   "year": 2005
+      #
+      # @example Find companies with SEC filings in or before a given year.
+      #   "year>=": 2003
+      #
+      # @example Find companies with SEC filings in or after a given year.
+      #   "year<=": 2007
+      #
+      # @example Find companies that appear as "filers" in SEC filings or as
+      # subsidiaries ("relationships") only.
+      #   "source_type": "relationships"
+      #
+      # @example Find companies with three direct descendants in a hierarchy.
+      #   "num_children": 3
+      #
+      # @example Find companies with two direct ancestors in a hierarchy.
+      #   "num_parents": 2
+      #
+      # @example Find companies within the hierarchy of another company.
+      #   "top_parent_id": "cw_7324"
+      class CorpWatch < Request
+        @base_url = 'http://api.corpwatch.org/%<year>s/companies.json'
+
+        # Returns the URL to request.
+        #
+        # @return [String] the URL to request
+        def to_s
+          params = convert
+          if params.key?(:year)
+            "#{base_url % params.slice(:year).symbolize_keys}?#{to_query(params.except(:year))}"
+          else
+            "http://api.corpwatch.org/companies.json?#{to_query(params)}"
+          end
+        end
+
+        # Converts the MQL parameters to API-specific parameters.
+        #
+        # @return [Hash] API-specific parameters
+        # @see http://api.corpwatch.org/documentation/api_examples.html#A17
+        def convert
+          match('company_name', 'name')
+          equal('limit', 'limit')
+
+          input['identifiers'] && input['identifiers'].each do |identifier|
+            case identifier['scheme']
+            when 'IRS Employer Identification Number'
+              equal('irs_number', 'identifier', input: identifier)
+            when 'SEC Central Index Key'
+              equal('cik', 'identifier', input: identifier)
+            end
+          end
+
+          input['contact_details'] && input['contact_details'].each do |contact_detail|
+            if contact_detail['type'] == 'address' && (contact_detail['value'] || contact_detail['value~='])
+              output['raw_address'] = contact_detail['value'] || contact_detail['value~=']
+            end
+          end
+
+          # API-specific parameters.
+          equal('key', 'corp_watch_api_key')
+          # http://api.corpwatch.org/documentation/api_examples.html#A35
+          equal('sic_code', 'industry_code')
+          equal('sic_sector', 'sector_code')
+          equal('substring_match', 'substring_match', valid: [1])
+          # http://api.corpwatch.org/documentation/api_examples.html#A36
+          equal('country_code', 'country_code', transform: lambda{|v| v.upcase})
+          equal('subdiv_code', 'subdiv_code', transform: lambda{|v| v.upcase})
+          equal('year', 'year')
+          equal('min_year', 'year>=')
+          equal('max_year', 'year<=')
+          equal('source_type', 'source_type')
+          equal('num_children', 'num_children')
+          equal('num_parents', 'num_parents')
+          equal('top_parent_id', 'top_parent_id')
+
+          output
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+module WhosGotDirt
+  module Requests
+    module Entity
+      # Requests for entities from the LittleSis API.
+      #
+      # Tokens less than two characters long will be ignored by LittleSis' `q`
+      # filter. The `q` parameter matches names and aliases. If `search_all` is
+      # `1`, it also matches descriptions and summaries.
+      #
+      # @example Supply an API key.
+      #   "little_sis_api_key": "..."
+      #
+      # @example Match descriptions and summaries on `name~=` queries.
+      #   "search_all": 1
+      class LittleSis < Request
+        # The JSON response has less metadata, e.g. number of results.
+        @base_url = 'https://api.littlesis.org/entities.xml'
+
+        # Returns the URL to request.
+        #
+        # @return [String] the URL to request
+        def to_s
+          "#{base_url}?#{to_query(convert)}"
+        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 http://api.littlesis.org/documentation#entities
+        # @see http://api.littlesis.org/entities/types.json
+        def convert
+          match('q', 'name')
+          one_of('type_ids', 'classification')
+          equal('num', 'limit')
+
+          # API-specific parameters.
+          equal('_key', 'little_sis_api_key')
+          equal('search_all', 'search_all', valid: [1])
+
+          output
+        end
+      end
+    end
+  end
+end