thaler 0.1.0

The Thaler API: financial data from SEC filings, with the source filing for every value.
Documentation

thaler

The Thaler API from Rust: financial data from SEC filings, with the source filing for every value.

cargo add thaler tokio --features tokio/full
use thaler::{Client, MetricPeriod};

#[tokio::main]
async fn main() -> Result<(), thaler::Error> {
    let client = Client::from_env()?; // THALER_API_KEY; or Client::new("thaler_…")

    let rows = client
        .metrics("AAPL")
        .period(MetricPeriod::Annual)
        .keys(["revenue", "net_income"])
        .send()
        .await?;
    for row in &rows.data {
        let source = row.read_from.as_ref().map_or("", |s| s.accession_number.as_str());
        println!("{} {} {} {source}", row.end_date, row.metric_key, row.value);
    }
    // 2025-09-27 revenue 416161000000 0000320193-25-000079
    Ok(())
}

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 std::time::Duration;

let client = thaler::Client::builder()
    .api_key("thaler_…")                       // or THALER_API_KEY
    .timeout(Duration::from_secs(30))          // to wait for an answer
    .max_retries(2)                            // tries after the first, on 429, 5xx or a lost connection
    .max_concurrent(4)                         // requests in flight; the API allows four
    .max_retry_after(Duration::from_secs(60))  // 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 thaler::{Clause, Op, ScreenColumn, SortDirection};

let big_and_profitable = client
    .screen()
    .filter(Clause::new(ScreenColumn::Revenue, Op::Gte, 10_000_000_000_u64))
    .filter(Clause::new(ScreenColumn::NetMargin, Op::Gt, 0.2))
    .sort(ScreenColumn::Revenue)
    .dir(SortDirection::Desc)
    .columns([ScreenColumn::Revenue, ScreenColumn::NetMargin, ScreenColumn::MarketCap])
    .send()
    .await?;
for row in &big_and_profitable.data {
    println!("{} {:?} {:?}", row.ticker, row.revenue, row.net_margin);
}
println!("{:?} matches", big_and_profitable.meta.total);

let every_row = client
    .screen()
    .filter(Clause::new(ScreenColumn::FcfMargin, Op::Gte, 0.15))
    .all(1000)
    .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 chrono::NaiveDate;

let then = client
    .metrics("KHC")
    .period(MetricPeriod::Annual)
    .keys(["net_income"])
    .as_of(NaiveDate::from_ymd_opt(2019, 3, 1).unwrap())
    .send()
    .await?;
let now = client.metrics("KHC").period(MetricPeriod::Annual).keys(["net_income"]).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 thaler::{ApiErrorKind, Error};

match client.profile("ZZZZ").send().await {
    Ok(answer) => println!("{}", answer.data.entity_name),
    Err(Error::Api(error)) => match error.kind() {
        ApiErrorKind::NotFound => println!("{} {} {}", error.code_text, error.detail, error.request_id),
        ApiErrorKind::RateLimited => println!("wait {:?}; {:?}", error.retry_after, error.violated_policies),
        _ => println!("{} {}", error.status, error.code_text),
    },
    Err(Error::Transport { source, .. }) => println!("no answer: {source}"),
    Err(error) => println!("{error}"),
}

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.