sec

package module
v0.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 17, 2022 License: MIT Imports: 16 Imported by: 0

README

SEC Client

This is an unofficial client for accessing the filing APIs that the Securities and Exchange Commision provides.

NOTE: This is a work in progress and is subject to change.

Installation

go get github.com/pixelguy95/sec

Built using golang version 1.18

Usage

Create a new client instance using sec.NewClient(), then use the client to access the ticker and filing data. Below is an example where all Non-current liabilities (See US-GAAP, and XBRL) are fetched for Apple Inc.

secClient := sec.NewClient()

appleTicker, err := secClient.GetTickerForSymbol("AAPL")
if err != nil {
    panic(err)
}

appleFacts, err := secClient.GetAllFactsForTicker(appleTicker)
if err != nil {
    panic(err)
}

nonCurrentLiabilities := appleFacts.Facts.UsGAAP["LiabilitiesNoncurrent"].Units["USD"]
for _, unit := range nonCurrentLiabilities {
    fmt.Printf("Non-current liabilities @ %s: %12.2f$\n", unit.End, unit.Value)
}

...
Non-current liabilities @ 2020-09-26: 153157000000.00$
Non-current liabilities @ 2020-12-26: 155323000000.00$
Non-current liabilities @ 2021-03-27: 161595000000.00$
Non-current liabilities @ 2021-06-26: 157806000000.00$
Non-current liabilities @ 2021-09-25: 162431000000.00$
Non-current liabilities @ 2021-12-25: 161685000000.00$
Non-current liabilities @ 2022-03-26: 155755000000.00$
...

To get a list of all possible tickers use secClient.GetAllTickers()

Persistence layer

This client intends to follow the compliance guidance set by SEC (See next section). One of the more significant limits set, is the limit to the number of data requests you can do per second. To mitigate this the client supports a persistence layer that will be hit first before going to the actual source.

You can create your own persistence layer using the simple interface provided

type PersistenceLayer interface {
    SaveFacts(Ticker, *CompanyFacts) error
    LoadFacts(Ticker) (*CompanyFacts, error)
}

The default behaviour of sec.NewClient() is to always go to the source (SEC). To create a client with persistence use sec.NewClientWithPersistence()

A basic persistence layer using bbolt is provided out of the box. For example:

persistenceLayerConfig := BoltPersistenceLayerConfig{Path: tempFile.Name(), ExpiresAfter: time.Hour}
bolt, err = NewBoltPersistenceLayer(persistenceLayerConfig)
if err != nil {
    panic(err)
}

clientWithPersistenceLayer := sec.NewClientWithPersistence(bolt)
Bulk data

Getting filing data from all companies individually would be very time consuming with the rate limit set by SEC. Becasue of that a bulk function is provided that gets fetches ALL company data in one go. client.GetBulk() returns a channel that will eventually contain all the data.

The latency and throughput of the bulk function is highly bandwidth and processing speed dependent. You can expect that it will take ~1 minute or so before the first ticker fact pair appears on the channel.

client := NewClient()
factChannel, err := client.GetBulk()
if err != nil {
    panic(err)
}

for tickerFact := range factChannel {
    fmt.Println(tickerFact)
}

Compliance

Coming soon

Documentation

Index

Constants

View Source 
const SECDateFormat = "2006-01-02"

Variables

This section is empty.

Functions

func CompleteUrl 

func CompleteUrl(partial string) string

func StandardSecDateFormatParse 

func StandardSecDateFormatParse(date string) (time.Time, error)

func StandardSecDateFormatParseSwallowError added in v0.3.1 

func StandardSecDateFormatParseSwallowError(date string) time.Time

Types

type Client added in v0.4.0 

type Client struct {
	// contains filtered or unexported fields
}

func NewClient added in v0.4.0 

func NewClient() *Client

NewClient creates a new client pointer without any persistence layer, meaning that all requests will go directly to sec.gov and will have to be rate limited.

func NewClientWithPersistence added in v0.4.0 

func NewClientWithPersistence(persistenceLayer PersistenceLayer) *Client

NewClientWithPersistence creates a new client pointer with given persistence layer implementation

func (*Client) GetAllFactsForTicker added in v0.4.0 

func (client *Client) GetAllFactsForTicker(ticker Ticker) (CompanyFacts, error)

func (*Client) GetAllTickers added in v0.4.0 

func (client *Client) GetAllTickers() ([]Ticker, error)

GetAllTickers Fetches all current tickers from the sec.gov api, uses caching for speed

func (*Client) GetBulk added in v0.4.0 

func (client *Client) GetBulk() (chan *TickerWithFacts, error)

GetBulk fetches ALL company facts, and provides them on the returned channel. This is highly dependent on your connection speed and your computational resources. Typically, it takes a minute or so before the first facts start appearing on the channel. Errors related to parsing of individual facts will be sent in the channel and will not be returned in this function call

func (*Client) GetTickerForCIK added in v0.4.0 

func (client *Client) GetTickerForCIK(cik uint64) (Ticker, error)

GetTickerForCIK returns the ticker with the given cik

func (*Client) GetTickerForSymbol added in v0.4.0 

func (client *Client) GetTickerForSymbol(symbol string) (Ticker, error)

GetTickerForSymbol returns the ticker with the given symbol

type CompanyFacts 

type CompanyFacts struct {
	CIK        uint64 `json:"cik"`
	EntityName string `json:"entityName"`
	Facts      Facts  `json:"facts"`
}

func (CompanyFacts) MarshalEasyJSON added in v0.4.0 

func (v CompanyFacts) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (CompanyFacts) MarshalJSON added in v0.4.0 

func (v CompanyFacts) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*CompanyFacts) UnmarshalEasyJSON added in v0.4.0 

func (v *CompanyFacts) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*CompanyFacts) UnmarshalJSON added in v0.4.0 

func (v *CompanyFacts) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type Fact 

type Fact struct {
	Label       string            `json:"label"`
	Description string            `json:"description"`
	Units       map[string][]Unit `json:"units"`
}

func (Fact) MarshalEasyJSON added in v0.4.0 

func (v Fact) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (Fact) MarshalJSON added in v0.4.0 

func (v Fact) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*Fact) UnmarshalEasyJSON added in v0.4.0 

func (v *Fact) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*Fact) UnmarshalJSON added in v0.4.0 

func (v *Fact) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type Facts 

type Facts struct {
	DEI    map[string]Fact `json:"dei"`
	UsGAAP map[string]Fact `json:"us-gaap"`
}

Facts A representation of a

func (Facts) MarshalEasyJSON added in v0.4.0 

func (v Facts) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (Facts) MarshalJSON added in v0.4.0 

func (v Facts) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*Facts) UnmarshalEasyJSON added in v0.4.0 

func (v *Facts) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*Facts) UnmarshalJSON added in v0.4.0 

func (v *Facts) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type PersistenceLayer added in v0.1.0 

type PersistenceLayer interface {
	SaveFacts(Ticker, *CompanyFacts) error
	LoadFacts(Ticker) (*CompanyFacts, error)
}

PersistenceLayer is an interface that you can use to create custom persistence layers for the sec client The client makes no assumption about thread safety, that has to be handled by the implementation if required

type Ticker 

type Ticker struct {
	// Central Index Key (CIK) is used on the SEC's computer systems to identify corporations
	// and individual people who have filed disclosure with the SEC
	CIK uint64 `json:"cik_str"`

	// The symbol of the company for example NDAQ
	Symbol string `json:"ticker"`

	// The name of the company
	Name string `json:"title"`
}

Ticker Represents a ticker in the given SEC format

type TickerWithFacts added in v0.4.0 

type TickerWithFacts struct {
	Ticker       Ticker
	CompanyFacts CompanyFacts
	Error        error
}

type Unit 

type Unit struct {
	Value float64 `json:"val"`

	Start string `json:"start"`
	End   string `json:"end"`

	FiscalYear   uint16 `json:"fy"`
	FiscalPeriod string `json:"fp"`

	Account string `json:"accn"`

	Form    string `json:"form"`
	FiledOn string `json:"filed"`
}

func (*Unit) EndAsTime added in v0.3.1 

func (unit *Unit) EndAsTime() time.Time

func (*Unit) FiledOnAsTime added in v0.3.1 

func (unit *Unit) FiledOnAsTime() time.Time

func (*Unit) IsInstant added in v0.3.1 

func (unit *Unit) IsInstant() bool

func (*Unit) IsPeriod added in v0.3.1 

func (unit *Unit) IsPeriod() bool

func (*Unit) IsQuarterRange added in v0.3.1 

func (unit *Unit) IsQuarterRange() bool

func (*Unit) IsYearRange added in v0.3.1 

func (unit *Unit) IsYearRange() bool

func (Unit) MarshalEasyJSON added in v0.4.0 

func (v Unit) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (Unit) MarshalJSON added in v0.4.0 

func (v Unit) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*Unit) StartAsTime added in v0.3.1 

func (unit *Unit) StartAsTime() time.Time

func (*Unit) UnmarshalEasyJSON added in v0.4.0 

func (v *Unit) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*Unit) UnmarshalJSON added in v0.4.0 

func (v *Unit) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.