edgar

README

edgar

A Go library for accessing the SEC's EDGAR database.

Installation

go get github.com/joeychilson/edgar

Example

package main

import (
	"context"
	"log"

	"github.com/joeychilson/edgar"
)

func main() {
	ctx := context.Background()

	// You should set a custom user agent or you will be rate limited.
	client := edgar.NewClient(edgar.WithUserAgent("CompanyName <contact@email.com>"))

	tickers, err := client.SearchCompanies(ctx, &edgar.CompanyFilterOptions{
		Tickers: []string{"AAPL"},
	})
	if err != nil {
		log.Fatal(err)
	}

	filings, err := client.Filings(ctx, tickers[0].CIK, &edgar.FilingFilterOptions{
		Forms: []string{"10-K"},
	})
	if err != nil {
		log.Fatal(err)
	}

	files, err := client.FilingDirectory(ctx, tickers[0].CIK, filings[0].AccessionNumber, &edgar.FilingDirectoryFilterOptions{
		DocumentName: filings[0].PrimaryDocument,
	})
	if err != nil {
		log.Fatal(err)
	}

	contents, err := client.FileContents(ctx, files[0].URL)
	if err != nil {
		log.Fatal(err)
	}

	log.Println(string(contents))
}

Documentation

Index

• type Client
  • func NewClient(options ...ClientOption) *Client
  • func (c *Client) FileContents(ctx context.Context, url string) ([]byte, error)
  • func (c *Client) Filer(ctx context.Context, cik string) (*Filer, error)
  • func (c *Client) FilerDirectory(ctx context.Context, cik string, opts *FilerDirectoryFilterOptions) ([]*DirectoryEntry, error)
  • func (c *Client) FilingDirectory(ctx context.Context, cik string, accessionNumber string, ...) ([]*DirectoryEntry, error)
  • func (c *Client) Filings(ctx context.Context, cik string, opts *FilingFilterOptions) ([]*Filing, error)
  • func (c *Client) SearchCompanies(ctx context.Context, opts *CompanyFilterOptions) ([]*CompanyMatch, error)
  • func (c *Client) SearchFilers(ctx context.Context, opts *FilerFilterOptions) ([]*FilerMatch, error)
• type ClientOption
  • func WithHTTPClient(httpClient *http.Client) ClientOption
  • func WithUserAgent(userAgent string) ClientOption
• type CompanyFilterOptions
• type CompanyMatch
• type DirectoryEntry
• type Filer
• type FilerDirectoryFilterOptions
• type FilerFilterOptions
• type FilerMatch
• type Filing
• type FilingDirectoryFilterOptions
• type FilingFilterOptions

Types

type Client

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

Client is a http client for interacting with EDGAR

func NewClient

func NewClient(options ...ClientOption) *Client

NewClient creates a new EDGAR client

func (*Client) FileContents

func (c *Client) FileContents(ctx context.Context, url string) ([]byte, error)

FileContents retrieves the contents of a file at the specified URL

func (*Client) Filer

func (c *Client) Filer(ctx context.Context, cik string) (*Filer, error)

Filer retrieves a filer's profile information

func (*Client) FilerDirectory

func (c *Client) FilerDirectory(ctx context.Context, cik string, opts *FilerDirectoryFilterOptions) ([]*DirectoryEntry, error)

FilerDirectory retrieves the contents of a specific filer directory

func (*Client) FilingDirectory

func (c *Client) FilingDirectory(ctx context.Context, cik string, accessionNumber string, opts *FilingDirectoryFilterOptions) ([]*DirectoryEntry, error)

FilingDirectory retrieves the contents of a specific filing directory

func (*Client) Filings

func (c *Client) Filings(ctx context.Context, cik string, opts *FilingFilterOptions) ([]*Filing, error)

Filings retrieves and filters filings for a given CIK

func (*Client) SearchCompanies

func (c *Client) SearchCompanies(ctx context.Context, opts *CompanyFilterOptions) ([]*CompanyMatch, error)

SearchCompanies retrieves a list of company ticker symbols and exchange information

func (*Client) SearchFilers

func (c *Client) SearchFilers(ctx context.Context, opts *FilerFilterOptions) ([]*FilerMatch, error)

SearchFilers retrieves and filters filer names and CIK numbers

type ClientOption

type ClientOption func(*Client)

ClientOption allows for customization of the client

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) ClientOption

WithHTTPClient allows custom HTTP client configuration

func WithUserAgent

func WithUserAgent(userAgent string) ClientOption

WithUserAgent sets a custom user agent string

type CompanyFilterOptions

type CompanyFilterOptions struct {
	Tickers   []string // Filter by specific ticker symbols
	CIKs      []string // Filter by specific CIK numbers
	Exchanges []string // Filter by specific exchanges
	Contains  string   // Filter company names containing this string (case-insensitive)
	Limit     int      // Limit the number of results
}

CompanyFilterOptions provides filtering options for company tickers

type CompanyMatch

type CompanyMatch struct {
	CIK          string `json:"cik"`
	Name         string `json:"name"`
	Ticker       string `json:"ticker"`
	ExchangeName string `json:"exchangeName"`
}

CompanyMatch represents a company name to CIK mapping

type DirectoryEntry

type DirectoryEntry struct {
	LastModified time.Time `json:"lastModified"`
	Name         string    `json:"name"`
	URL          string    `json:"url"`
	Size         int64     `json:"size,omitempty"`
}

DirectoryEntry represents a single file in a directory listing

type Filer

type Filer struct {
	CIK                  string   `json:"cik"`
	EntityType           string   `json:"entityType"`
	SIC                  string   `json:"sic"`
	SICDescription       string   `json:"sicDescription"`
	Name                 string   `json:"name"`
	Tickers              []string `json:"tickers"`
	Exchanges            []string `json:"exchanges"`
	EIN                  string   `json:"ein"`
	Description          string   `json:"description"`
	Website              string   `json:"website"`
	Category             string   `json:"category"`
	FiscalYearEnd        string   `json:"fiscalYearEnd"`
	StateOfIncorporation string   `json:"stateOfIncorporation"`
	PhoneNumber          string   `json:"phoneNumber"`
	Flags                string   `json:"flags"`
}

Filer represents a filer's profile information

type FilerDirectoryFilterOptions

type FilerDirectoryFilterOptions struct {
	StartDate time.Time // Filter entries modified after this date
	EndDate   time.Time // Filter entries modified before this date
	Limit     int       // Limit the number of results
}

FilerDirectoryFilterOptions provides filtering options for index entries

type FilerFilterOptions

type FilerFilterOptions struct {
	Contains string   // Filter filer names containing this string (case-insensitive)
	CIKs     []string // Filter by specific CIK numbers
	Limit    int      // Limit number of results
}

FilerFilterOptions provides filtering options for filer searches

type FilerMatch

type FilerMatch struct {
	Name string `json:"name"`
	CIK  string `json:"cik"`
}

FilerMatch represents an entity name to CIK mapping

type Filing

type Filing struct {
	AccessionNumber            string    `json:"accessionNumber"`
	Form                       string    `json:"form"`
	FilingDate                 time.Time `json:"filingDate"`
	ReportDate                 time.Time `json:"reportDate,omitempty"`
	AcceptanceTime             time.Time `json:"acceptanceDateTime"`
	Act                        string    `json:"act,omitempty"`
	Size                       int       `json:"size"`
	Items                      []string  `json:"items,omitempty"`
	IsXBRL                     bool      `json:"isXBRL"`
	IsInlineXBRL               bool      `json:"isInlineXBRL"`
	PrimaryDocument            string    `json:"primaryDocument"`
	PrimaryDocumentDescription string    `json:"primaryDocumentDescription"`
}

Filing represents a single filing submission

type FilingDirectoryFilterOptions

type FilingDirectoryFilterOptions struct {
	DocumentName  string // Filter by document name
	FileExtension string // Filter by document extension (e.g., ".htm", ".xml")
	Limit         int    // Limit the number of results
}

FilingDirectoryFilterOptions provides filtering options for filing directory entries

type FilingFilterOptions

type FilingFilterOptions struct {
	StartDate time.Time
	EndDate   time.Time
	Forms     []string
	Limit     int
}

FilingFilterOptions is used to filter filings