thaler
The Thaler API from Rust: financial data from SEC filings, with the source filing for every value.
use ;
async
Every figure is a Decimal (the digits as filed; a float loses digits
past the fifteenth), every day a chrono::NaiveDate, and every answer a
Response with the request ID and the account’s limits beside its
data. Create a key at
thaler.sh/developers/keys.
What the client does
At most four requests are in flight at once. When the minute’s sixty are
spent, the next request waits for the reset. A 429 is retried after its
Retry-After; one longer than a minute, the month’s limit, is returned
as an error at once.
A 500, 502, 503 or 504, or a connection that failed, is retried twice
after a growing pause; those answers don’t count against the month. A
400, 401 or 404 is returned as it stands, and a Screener clause the API
would refuse is Error::Config before anything is sent.
Figures are Decimal (the digits as filed), days are NaiveDate,
instants are DateTime<Utc>, enums are enums with an Unknown variant
for a value a later API adds, and Option marks what can be absent or
null. An answer that is not as documented is Error::Decode, naming the
field.
all() on the Screener, holders, a holder’s positions and insider
activity collects rows across pages.
One Error enum: Api with the problem’s code, detail and
request_id and a kind() (NotFound, Authentication,
BadRequest, RateLimited, Server), Transport with reqwest’s
cause, Decode, and Config.
Built on reqwest and tokio (a runtime with its time driver, as
#[tokio::main] makes). TLS is rustls by default; for the platform’s
library instead, turn the default off and the native-tls feature on
(thaler = { version = "0.1", default-features = false, features = ["native-tls"] }; with both on, reqwest picks native TLS). The
rust_decimal feature adds Decimal::to_decimal for arithmetic.
The client
use Duration;
let client = builder
.api_key // or THALER_API_KEY
.timeout // to wait for an answer
.max_retries // tries after the first, on 429, 5xx or a lost connection
.max_concurrent // requests in flight; the API allows four
.max_retry_after // the longest Retry-After waited for
.build?;
Client is cheap to clone; clones share connections and the account’s
limits, so one client serves a whole program. reqwest_client(...)
sends through a reqwest::Client of your own, for a proxy or a custom
TLS setup.
Every call
Each method returns a request; set what it takes, then send().await.
| Request | Answers with |
|---|---|
search_securities(query).limit() |
Vec<SecuritySearchHit> |
profile(ticker) |
SecurityProfile |
metrics(ticker).period().keys().collapse().limit().as_of() |
Vec<MetricValue> |
metric_catalog() |
Vec<MetricCatalogEntry> |
metric_lineage(ticker, key).metric_value_id().limit().as_of() |
Vec<MetricLineage> |
metric_revisions(ticker, key).metric_value_id().fiscal_year().fiscal_period().limit() |
Vec<MetricRevision> |
raw_concepts(ticker).limit() |
Vec<RawConcept> |
filings(ticker).forms().items().limit() |
Vec<Filing> |
filings_day().date() |
FilingsDay |
filing(accession) |
FilingSource |
insider_activity().ticker().tickers().since().kind().limit().offset() |
InsiderActivityPage |
search_holders().query().limit() |
Vec<HolderHit> |
holder(cik).limit().offset() |
Holder |
holders(ticker).limit().offset() |
SecurityHolders |
segments(ticker).period() |
Segments |
prices(ticker).range().from().to() |
Prices |
screen().filter().where_().sort().dir().limit().offset().columns() |
Vec<ScreenRow> |
release() |
Release |
Each send() resolves to a Response: .data as above, .meta (the
route, the parameters as the API read them, the Screener’s counts, the
release), .request_id, .etag, .rate_limit and .headers.
The Screener
use ;
let big_and_profitable = client
.screen
.filter
.filter
.sort
.dir
.columns
.send
.await?;
for row in &big_and_profitable.data
println!;
let every_row = client
.screen
.filter
.all
.await?;
Clause writes a filter as the API takes it (revenue:gte:10000000000,
never scientific notation); where_ takes one written by hand.
Point-in-time reads
use NaiveDate;
let then = client
.metrics
.period
.keys
.as_of
.send
.await?;
let now = client.metrics.period.keys.send.await?;
Each value comes from the latest filing on or before the day, so a backtest only sees what was public at the time. See the guide on point-in-time data.
Errors
use ;
match client.profile.send.await
Prices
Prices include IEX’s last sale for each trading day. Data provided for free by IEX. By accessing or using IEX Historical Data, you agree to the IEX Historical Data Terms of Use.
Versions
The crate is 0.x while the API is in beta. thaler::API_VERSION names
the API document a release follows. The minimum supported Rust version
is 1.85. Changes are in CHANGELOG.md.