capital-iq¶ ↑

Ruby API wrapper to Capital IQ API.

Compatibility Warning¶ ↑

Breaking changes were introduced in versions following v0.0.7. This was necessary to provide support for new features such as multi-identifier/multi-mnemonic calls.

v0.0.7 design is no longer maintained and can be found here: github.com/exitround/capital-iq/tree/v0.0.7

Installation¶ ↑

gem install capital-iq

Capital IQ API Basics¶ ↑

Each request to Capital IQ API contains three required parameters: function, identifier, mnemonic, and one optional parameter: properties. The corresponding result will contain a rowset with “headers” and “rows”. For single-value mnemonics the result would usually consist of a single header and a single row. The header name would usually match the name of the input mnemonic. Multi-value mnemonics, however, often contain additional headers (such as “change date” etc) and multiple rows.

Please refer to Capital IQ support and documentation for specific function/mnemonic instructions and data retrieval pricing information.

Gem Usage¶ ↑

To start, initialize the client object with the user name and password. This example assumes that they are stored in the environment variables:

client = CapitalIQ::Client.new(ENV['CAPIQ_USER'], ENV['CAPIQ_PWD'])

API Calls Based on Request Objects¶ ↑

This is the most basic way of using the gem. Create a request, call the api, get the result. Here, the function is GDSHE, the identifier is ‘microsoft’ and the mnemonic is IQ_COMPANY_ID_QUICK_MATCH:

req = CapitalIQ::Request.new(CapitalIQ::Functions::GDSHE, 'microsoft', 'IQ_COMPANY_ID_QUICK_MATCH')
res = client.base_request(req)

You have an option of passing multiple requst objects into a call. They are all executed in one round trip. Beware of the API limits however.

req1 = CapitalIQ::Request.new(CapitalIQ::Functions::GDSHE, 'microsoft', 'IQ_COMPANY_ID_QUICK_MATCH')
req2 = CapitalIQ::Request.new(CapitalIQ::Functions::GDSHE, 'google', 'IQ_COMPANY_ID_QUICK_MATCH')
res = client.base_request([req1, req2])

Convenience Methods - request_xxxxx¶ ↑

You may choose to use the convenience methods provided by the Client class - request_xxxxx, where xxxxx - is the name of Capital IQ API function). They allow to forgo creating the request objects explicity, (the requsts objects do get created underneath though):

res = client.request_gdshe('microsoft', 'IQ_COMPANY_ID_QUICK_MATCH', {startRank:1, endRank:20})

The returned values are accessed by the identifier and the header name:

res_val = res['microsoft']['IQ_COMPANY_ID_QUICK_MATCH']

When using GDSHE or GDSHV functions, the result is represented by an array. Therefore res_val above is an array. We’ll use first method to get the actual value:

ms_id = res_val.first

You can use the scalar method when querying on a single identifier, so the above example can be shortened to:

ms_id = res.scalar['IQ_COMPANY_ID_QUICK_MATCH'].first

Multiple identifier / single mnemonic requests¶ ↑

This example generates two requests:

res = client.request_gdshe(['microsoft', 'google'], 'IQ_COMPANY_ID_QUICK_MATCH', {startRank:1, endRank:20})
ms_id = res['microsoft']['IQ_COMPANY_ID_QUICK_MATCH'].first
google_id = res['google']['IQ_COMPANY_ID_QUICK_MATCH'].first

Multiple identifier / multiple mnemonic queries¶ ↑

This call generates (2 identifiers times 3 mnemonics) = 6 requests (they’re still executed in a batch)

res = client.request_gdsp([ms_id, google_id], %w(IQ_COMPANY_WEBSITE IQ_COMPANY_NAME IQ_BUSINESS_DESCRIPTION))

You can use the to_hash method to retrieve all values for a given identifier

# All values for +ms_id+
ms_data = res[ms_id].to_hash

Or you can retrieve all values for all identifiers:

all_data = res.to_hash

Contributing to capital-iq¶ ↑

• Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet.

• Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it.

• Fork the project.

• Start a feature/bugfix branch.

• Commit and push until you are happy with your contribution.

• Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.

• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright¶ ↑

Copyright © 2014 Exitround. See LICENSE.txt for further details.