Class: WhosGotDirt::Requests::Entity::CorpWatch

Inherits:
WhosGotDirt::Request show all
Defined in:
lib/whos_got_dirt/requests/entity/corp_watch.rb

Overview

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 will be ignored. If substring_match is 1, queries will match within words as well as complete words, at a severe performance penalty.

subsidiaries ("relationships") only. "source_type": "relationships"

Examples:

Supply an API key.

"corp_watch_api_key": "..."

Find entities by IRS Employer Identification Number (EIN).

"identifiers": [{
  "identifier": "911653725",
  "scheme": "IRS Employer Identification Number"
}]

Find entities by SEC Central Index Key (CIK).

"identifiers": [{
  "identifier": "37996",
  "scheme": "SEC Central Index Key"
}]

Find companies by SIC code.

"industry_code": "2011"

Find companies by SIC sector.

"sector_code": "4100"

Match within words on name and address queries.

"substring_match": 1

Find companies by country code.

"country_code": "US"

Find companies by country subdivision code.

"subdiv_code": "OR"

Find companies with SEC filings in a given year.

"year": 2005

Find companies with SEC filings in or before a given year.

"year>=": 2003

Find companies with SEC filings in or after a given year.

"year<=": 2007

Find companies that appear as "filers" in SEC filings or as

Find companies with three direct descendants in a hierarchy.

"num_children": 3

Find companies with two direct ancestors in a hierarchy.

"num_parents": 2

Find companies within the hierarchy of another company.

"top_parent_id": "cw_7324"

Instance Method Summary collapse

Constructor Details

This class inherits a constructor from WhosGotDirt::Request

Instance Method Details

#convert ⇒ Hash

Converts the MQL parameters to API-specific parameters.

Returns:

  • (Hash) —

    API-specific parameters

See Also:



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/whos_got_dirt/requests/entity/corp_watch.rb', line 82

def convert
  match('company_name', 'name')
  equal('limit', 'limit') # default 100, maximum 5000
  equal('index', 'page', transform: lambda{|v| (v - 1) * (input['limit'] || 100)})

  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

#to_s ⇒ String

Returns the URL to request.

Returns:

  • (String) —

    the URL to request



69
70
71
72
73
74
75
76
 
# File 'lib/whos_got_dirt/requests/entity/corp_watch.rb', line 69

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