Documentation
¶
Overview ¶
Package edgar is the HTTP client layer for SEC EDGAR. It enforces the two rules EDGAR rejects requests over: a present User-Agent header and the 10 req/sec rate cap.
Index ¶
- func CompanionURL(cik int64, filing Filing, name string) string
- func DocumentURL(cik int64, filing Filing) string
- type Client
- func (c *Client) FetchPrimaryDocument(ctx context.Context, cik int64, filing Filing) ([]byte, error)
- func (c *Client) FilingByAccession(ctx context.Context, cik int64, accession string) (Filing, error)
- func (c *Client) FilingFiles(ctx context.Context, cik int64, filing Filing) ([]string, error)
- func (c *Client) FilingForYear(ctx context.Context, cik int64, formType string, year int) (Filing, error)
- func (c *Client) Filings(ctx context.Context, cik int64, formType string) ([]Filing, error)
- func (c *Client) Get(ctx context.Context, url string) ([]byte, error)
- func (c *Client) LatestFiling(ctx context.Context, cik int64, formType string) (Filing, error)
- func (c *Client) LookupCIK(ctx context.Context, ticker string) (int64, error)
- type ErrNoFiling
- type ErrNoFilingByAccession
- type ErrUnknownTicker
- type Filing
- type Option
- type StatusError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CompanionURL ¶
CompanionURL builds the Archives URL for another file in the same filing directory as the primary document — an XBRL linkbase or schema, for instance.
func DocumentURL ¶
DocumentURL builds the EDGAR Archives URL for a filing's primary document. Example: CIK 320193, accession 0000320193-24-000123, document aapl-20240928.htm →https://www.sec.gov/Archives/edgar/data/320193/000032019324000123/aapl-20240928.htm
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client issues rate-limited, User-Agent-identified requests to SEC EDGAR. One Client owns one rate limiter; share a single Client across goroutines to keep concurrent fetches under the global rate cap.
func NewClient ¶
NewClient reads SEC_CLI_USER_AGENT from the environment and returns a Client. EDGAR's Fair Access policy requires every request identify the caller; a missing or empty env var returns an error here instead of letting EDGAR answer 403 on the wire. Options override defaults (e.g. WithHTTPClient for tests).
func (*Client) FetchPrimaryDocument ¶
func (c *Client) FetchPrimaryDocument(ctx context.Context, cik int64, filing Filing) ([]byte, error)
FetchPrimaryDocument returns the raw bytes of a filing's primary document. It does not interpret the bytes — classifying the format is the router's job (Phase 4).
func (*Client) FilingByAccession ¶
func (c *Client) FilingByAccession(ctx context.Context, cik int64, accession string) (Filing, error)
FilingByAccession returns the filing matching the exact accession number, regardless of form type. Accession comparison is case-insensitive and strips dashes so both "0000320193-24-000123" and "000032019324000123" match.
func (*Client) FilingFiles ¶
FilingFiles lists the file names in a filing's Archives directory, read from the directory's index.json. It is how callers discover the linkbase and schema companions whose names aren't carried in the submissions metadata.
func (*Client) FilingForYear ¶
func (c *Client) FilingForYear(ctx context.Context, cik int64, formType string, year int) (Filing, error)
FilingForYear returns the filing of formType whose filing date falls in the given calendar year. When more than one qualifies (e.g. an amendment filed the same year), the most recently filed wins. It returns *ErrNoFiling when no filing of that form was filed in that year.
func (*Client) Filings ¶
Filings returns every filing of formType for cik, newest first. The form match is exact (e.g. "10-K" does not match "10-K/A"). An empty result is not an error — callers that need one filing use LatestFiling or FilingForYear.
func (*Client) Get ¶
Get fetches url and returns the response body. It blocks on the shared rate limiter, sets the User-Agent header, retries once on 5xx with a 500ms delay, and returns *StatusError for any non-2xx response.
func (*Client) LatestFiling ¶
LatestFiling returns the most recent filing of formType for cik. It returns *ErrNoFiling when the company has filed none.
type ErrNoFiling ¶
ErrNoFiling is returned by LatestFiling and FilingForYear when no filing matches the requested form type (and year).
func (*ErrNoFiling) Error ¶
func (e *ErrNoFiling) Error() string
type ErrNoFilingByAccession ¶
ErrNoFilingByAccession is returned by FilingByAccession when no filing in the submissions history matches the requested accession number.
func (*ErrNoFilingByAccession) Error ¶
func (e *ErrNoFilingByAccession) Error() string
type ErrUnknownTicker ¶
type ErrUnknownTicker struct{ Ticker string }
ErrUnknownTicker is returned by LookupCIK when a ticker is not in EDGAR's company_tickers map.
func (*ErrUnknownTicker) Error ¶
func (e *ErrUnknownTicker) Error() string
type Filing ¶
type Filing struct {
AccessionNumber string
FilingDate time.Time
ReportDate time.Time
Form string
PrimaryDocument string
}
Filing is one entry from a company's submission history.
type Option ¶
type Option func(*Client)
Option configures a Client at construction. Options exist mainly so tests can inject a fake transport; production callers use NewClient() with no options.
func WithHTTPClient ¶
WithHTTPClient sets the underlying *http.Client. It is the seam hermetic tests use to inject a fake http.RoundTripper (see internal/edgar/client_test.go), keeping the Client a pure HTTP client with no knowledge of test plumbing.
type StatusError ¶
StatusError is returned by Get for any non-2xx HTTP response. Callers can use errors.As to inspect the status code.
func (*StatusError) Error ¶
func (e *StatusError) Error() string
Source Files