ThirteenF

A ruby interface for S.E.C. 13F Data. There is a lot of great finance and investing data that is available for free, but few developer tools that let us interact with the data outside of commercial platforms. This library aims to remedy a small piece of this by providing a robust API to search and retrieve investment holdings data of institutional investors through 13F Reports. What is a 13F Report? Please visit this S.E.C. webpage for a full description.

This library is meant to serve a lightweight API which developers can enhance via a persistence layer and/or UI in their own applications.

At this time, I am sure there are a number of edge cases the gem does not handle. Also it only imports 13F's submitted as XML files, which only goes back to 2013. It is a low priority for myself to robustly parse the text files provided before this time.

Installation

Add this line to your application's Gemfile:

gem 'thirteen_f'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install thirteen_f

Usage

Search

search = ThirteenF::Search.new('Berkshire Hathaway')
search.get_results

result = search.results.first
result.get_entity
entity = result.entity

Entities

cik_number = '0001061768'
entity = ThirteenF::Entity.from_cik cik_number

entity.most_recent_filing
entity.get_most_recent_positions
entity.most_recent_positions # returns positions from the most recent 13F filing

entity.cik # type: String | ex: "0001067983"
entity.name # type: String | ex: "BERKSHIRE HATHAWAY INC"
entity.state_or_country # type: String | ex: "NE"

Filings

filing = entity.filings.first
filing.entity
filing.get_positions
filing.positions # returns the US public securities held by the entity at the
                 # time of the period of the report

filing.index_url # type: String
filing.period_of_report # type: Date or nil
filing.time_accepted # type: DateTime or nil
filing.table_html_url # type: String or nil
filing.table_xml_url # type: String or nil
filing.cover_page_html_url # String or nil

Positions

xml_url = 'https://www.sec.gov/Archives/edgar/data/1061768/000156761920003359/form13fInfoTable.xml'
positions = ThirteenF::Position.from_xml_url(xml_url)

position = filing.positions.first
position.filing

position.name_of_issuer # type: String | ex: "EBAY INC"
position.title_of_class # type: String | ex: "COM"
position.cusip # type: String | ex: "278642103"
position.value_in_thousands # type: Integer | ex: 722018
position.shares_or_principal_amount # type: Integer | ex: 19994970
position.shares_or_principal_amount_type # type: String | ex: "SH"
position.put_or_call # type: String or nil | ex: "PUT"
position.investment_discretion # type: String | ex: "DFND"
position.other_managers # type: String or nil | ex: "1,4,11"
position.voting_authority # type: Hash | ex: { sole: 19994970, shared: 0, none: 0 }

Net Securities

CUSIP Securities

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/savfischer/thirteen_f. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the ThirteenF project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.