Python SDK Guide

pip install valuein-sdk            # Python 3.11 or newer # or with uvuv add valuein-sdk                 # inside a uv projectuv pip install valuein-sdk         # into any virtual environment # optional: client.to_polars() needs the polars extrapip install "valuein-sdk[polars]"

# Optional. With no key the SDK reads the free sample (S&P 500, last 5 years).export VALUEIN_API_KEY="your_token" # Or keep it in a .env file. The SDK loads the first .env it finds from the# current directory upward, once per process. VALUEIN_NO_DOTENV=1 turns that off.echo 'VALUEIN_API_KEY=your_token' >> .env # In Python, an explicit key wins over the environment:#   ValueinClient(api_key="your_token")#   ValueinClient(api_key="")    # always the free sample

from valuein_sdk import ValueinClient # Apple's annual revenue, net income and diluted EPS, one row per fiscal year.# A 10-K repeats earlier years as comparatives, so keep only the latest-filed# value for each period before pivoting.sql = """WITH latest AS (    SELECT f.period_end, f.standard_concept, f.numeric_value    FROM fact f    JOIN "references" r ON r.cik = f.entity_id    WHERE r.symbol = 'AAPL'      AND r.is_active      AND f.fiscal_period = 'FY'      AND f.standard_concept IN ('TotalRevenue', 'NetIncome', 'EPSDiluted')    QUALIFY ROW_NUMBER() OVER (        PARTITION BY f.period_end, f.standard_concept        ORDER BY f.accepted_at DESC    ) = 1)SELECT    period_end,    MAX(CASE WHEN standard_concept = 'TotalRevenue' THEN numeric_value END) AS revenue,    MAX(CASE WHEN standard_concept = 'NetIncome'    THEN numeric_value END) AS net_income,    MAX(CASE WHEN standard_concept = 'EPSDiluted'   THEN numeric_value END) AS eps_dilutedFROM latestGROUP BY period_endORDER BY period_end DESC""" with ValueinClient() as client:  # no key: the free sample    print(client.plan)           # 'sample', 'sp500', 'pro' or 'full'    df = client.run_query(sql)   # pandas DataFrame    print(df)

from valuein_sdk import ValueinClient with ValueinClient() as client:    # What a ticker or CIK resolves to. A CIK also reaches delisted companies.    print(client.resolve(["AAPL", 320193]))     # One company's rows from a table, with the point-in-time filter applied.    facts = client.read_table(        "fact",        tickers="AAPL",        columns=["standard_concept", "period_end", "fiscal_period", "numeric_value"],        limit=10,    )    print(facts)     # Named SQL templates. Pass parameters as keyword arguments.    print(client.list_templates()[:5])    df = client.run_template("fundamentals_by_ticker", ticker="AAPL")    print(df.head())     # Links to the SEC filings behind the numbers.    links = client.filing_links("AAPL", form_types=["10-K"], limit=3)    print(links[["form_type", "filing_date", "document_url"]])     # Restatement Radar: figures a later filing changed (every plan).    changed = client.restatements(ticker="AAPL", limit=5)    print(changed[["standard_concept", "period_end", "first_value", "current_value", "disclosure_class"]])

from datetime import datetime, timezone from valuein_sdk import ValueinClient # With as_of set, fact, ratio, factor_scores, earnings_signals and the price# tables only show rows the SEC had accepted on or before that moment.as_of = datetime(2024, 1, 1, tzinfo=timezone.utc)  # must be timezone-aware sql = """SELECT f.period_end, f.numeric_value AS revenue, f.accepted_atFROM fact fJOIN "references" r ON r.cik = f.entity_idWHERE r.symbol = 'AAPL'  AND r.is_active  AND f.fiscal_period = 'FY'  AND f.standard_concept = 'TotalRevenue'QUALIFY ROW_NUMBER() OVER (PARTITION BY f.period_end ORDER BY f.accepted_at DESC) = 1ORDER BY f.period_end DESC""" with ValueinClient(as_of=as_of) as client:    print(client.run_query(sql))  # nothing accepted after 2024-01-01     # Index members on a past date, from index_membership.    members = client.pit_universe("2023-06-30")    print(members[["cik", "company_name", "ticker_at_date"]].head())

from valuein_sdk import ValueinClient # Current S&P 500 members with return on equity above 20% and debt-to-equity# below 1.0 in their latest annual ratios. `ratio` holds FY and TTM rows,# so filter fiscal_period.sql = """WITH members AS (    SELECT DISTINCT cik FROM index_membership    WHERE index_name = 'SP500' AND removal_date IS NULL),latest AS (    SELECT entity_id, ratio_name, value    FROM ratio    WHERE fiscal_period = 'FY'      AND ratio_name IN ('return_on_equity', 'debt_to_equity')    QUALIFY ROW_NUMBER() OVER (        PARTITION BY entity_id, ratio_name        ORDER BY period_end DESC    ) = 1)SELECT    r.symbol,    r.name,    r.sector,    MAX(CASE WHEN l.ratio_name = 'return_on_equity' THEN l.value END) AS roe,    MAX(CASE WHEN l.ratio_name = 'debt_to_equity'   THEN l.value END) AS debt_to_equityFROM latest lJOIN members m ON m.cik = l.entity_idJOIN "references" r ON r.cik = l.entity_id AND r.is_active AND r.is_primary_tickerGROUP BY r.symbol, r.name, r.sectorHAVING roe > 0.20 AND debt_to_equity < 1.0ORDER BY roe DESCLIMIT 20""" with ValueinClient() as client:    print(client.run_query(sql))     # Or use the precomputed factor table (ranks are 0-1, 1 = best).    top = client.factor_scores(sector="Information Technology", min_composite_rank=0.8, limit=10)    print(top[["symbol", "period_end", "roe", "composite_rank"]])

from valuein_sdk import ValueinClient with ValueinClient() as client:  # no key: the free sample    # Three statements as the market knew them, one column per fiscal year.    fin = client.financials("AAPL", freq="FY", periods=4)    print(fin.summary())    print(fin.statement("income").head(8))     # Trace one cell to the SEC filing it came from.    trail = fin.explain("TotalRevenue", "2024-09-28")    print(trail[["concept", "value", "form_type", "accession_id", "sec_url"]])

from valuein_sdk import ValueinClient with ValueinClient() as client:  # no key: the free sample    # A five-year DCF on Apple's reported free cash flow. You choose the growth    # rate; the SDK never guesses one. Inputs trace to filings.    dcf = client.dcf("AAPL", stage1_growth_rate=0.06)    print(dcf.projection_frame())      # projected cash flows and present values    print(dcf.sensitivity_frame())     # value per share across WACC and terminal growth     # Peer comparables from reported ratios.    peers = client.peers("AAPL", n=3)    print(peers[["ticker", "cik"]])

from valuein_sdk import ValueinClient with ValueinClient() as client:  # no key: the free sample    # The S&P 500 as it stood on 2024-12-31, keeping only names priced above $10.    # Every field is read as it was known on that date: no look-ahead.    screen = client.screen("2024-12-31", universe="SP500", min_price=10)    print(screen.describe())     # Screens are lazy. collect() runs it and returns the result.    result = screen.collect()    print(result)

from valuein_sdk import ValueinClient # Needs Pro or Institutional: the backtest reads daily prices.with ValueinClient() as client:  # reads VALUEIN_API_KEY    # Rank the S&P 500 on return on equity each quarter, using only data the    # SEC had accepted at each rebalance date. Long the top quintile, short the bottom.    result = client.factor_backtest(        "return_on_equity",        start="2020-01-31",        end="2023-12-31",        freq="QE",        lineage=True,  # keep the fact_id behind every signal value    )    print(result.summary())    print(result.to_frame().head())

from valuein_sdk import ValueinClient # Needs Pro or Institutional: the study reads daily prices.with ValueinClient() as client:  # reads VALUEIN_API_KEY    # The same factor study on three vintages of the data: point-in-time,    # as originally filed, and as restated today. The gap is what restatements    # would have hidden from a backtest that used today's numbers.    study = client.restatement_impact(        "return_on_equity", start="2020-01-31", end="2023-12-31"    )    print(study.summary())

import tempfilefrom pathlib import Path from valuein_sdk import ValueinClient out = Path(tempfile.mkdtemp()) / "apple-bundle" with ValueinClient() as client:  # no key: the free sample    # Write a point-in-time slice to disk: a few tables, one company.    # bundle.json records each file's SHA-256, the plan and the as_of cutoff.    client.write_bundle(out, tables=["entity", "references", "fact"], tickers=["AAPL"])    print(sorted(p.name for p in out.iterdir()))     # Mirror whole tables to disk. Re-running moves only what changed.    report = client.sync(out.parent / "mirror", tables=["entity", "index_membership"], verify=True)    print(report.downloaded) # Replay the bundle offline, with the same point-in-time views. Hashes are checked on load.with ValueinClient.from_bundle(out) as offline:    print(offline.is_offline)    print(offline.run_query("SELECT COUNT(*) AS facts FROM fact"))

from valuein_sdk import ValueinClient with ValueinClient() as client:  # no key: the free sample    print(client.plan)            # 'sample', 'sp500', 'pro' or 'full'    print(client.usage())         # rate budget used so far    print(client.capabilities())  # what this plan can read and do    print(client.diagnostics())   # versions, cache, connectivity

from valuein_sdk import (    ValueinClient,    ValueinError,    ValueinNotFoundError,    ValueinRateLimitError,    ValueinValidationError,) try:    with ValueinClient() as client:        df = client.read_table("fact", tickers="ZZZZZ", limit=5)except ValueinNotFoundError as e:    # An unknown ticker, or a CIK outside your plan's universe.    print(f"Not found: {e}")except ValueinValidationError as e:    # Bad input: a non-SELECT statement, a blocked function, a naive as_of.    print(f"Invalid request: {e}")except ValueinRateLimitError as e:    # Over your plan's per-minute or per-hour limit.    print(f"Rate limited, retry after {e.retry_after} s")except ValueinError as e:    # Base class of every SDK error (auth, plan, network, data).    print(f"Valuein error: {e}")

valuein tables                     # tables your plan can readvaluein schema fact                # columns and types, no downloadvaluein query "SELECT symbol, name, sector FROM \"references\" WHERE is_active LIMIT 5"