yukka

A Python client for YUKKA Lab's sentiment and financial data APIs. Pull news sentiment, entity resolution, and market data directly into your Python environment.

from yukka import Session, Asset
from yukka.data import Index

with Session() as session:  # reads YUKKA_TOKEN from environment
    bmw = Asset.from_isin("DE0005190003")
    df = session.sentiment(bmw, date_from="2026-01-01")

Installation

pip install yukka

Requires Python 3.13+.

Trial Mode (no token required)

You can explore the API without a token. Trial mode gives you access to 10 companies over the date range 2016-01-01 to 2024-12-31:

from yukka import Session, Asset

with Session() as session:  # no token needed
    apple = Asset.from_yukka_id("company:apple")
    df = session.sentiment(apple, "2020-01-01", "2020-12-31")

Requesting entities outside this list, dates outside the allowed range, or using entity resolution (e.g. Asset.from_isin()) will raise a TrialModeError. Features that need a token, such as Index.STOXX600, raise a MissingTokenError (a TrialModeError) that says how to set one.

Authentication

For full access to all entities, dates, and entity resolution, contact YUKKA Lab to request an API token.

Set the token as an environment variable:

export YUKKA_TOKEN="eyJ..."

Or pass it explicitly:

from yukka import Session

session = Session(token="eyJ...")

Quick Start

Using a pre-validated universe

Constituent lists come with their YUKKA IDs already resolved. The FTSE 100, S&P 500 and Nasdaq 100 ship with the package; the STOXX 600 is loaded from the Quant API and needs a token (YUKKA_TOKEN).

from yukka import Session, Asset
from yukka.data import Index

# Load STOXX 600 constituents as a Polars DataFrame (isin, ric, name, yukka_id, ...)
universe = Index.STOXX600.frame

# Create assets from YUKKA IDs and fetch sentiment
assets = Asset.from_yukka_id(universe["yukka_id"].to_list())

with Session() as session:
    df = session.sentiment(assets, date_from="2026-01-01", date_to="2026-02-01")

Where the STOXX 600 universe comes from

Index.STOXX600 reads the universe yl-quant produces daily, served by the Quant API. It needs a token: YUKKA_TOKEN, or token=... to set_universe_source(). Without one it raises a MissingTokenError before any request. Each day is an immutable snapshot, so a strategy run and the research that reproduces it can pin the same one (also via YUKKA_UNIVERSE_PULL_DATE):

from yukka.data import Index, set_universe_source

set_universe_source(pull_date="2026-09-22")  # token from YUKKA_TOKEN
membership = Index.STOXX600.membership_history  # date, rank, ric, ... (long format)

Names are keyed by their current RIC (INGA.AS, not ING.AS). Before 1.0 the SDK read public R2 parquet files by default (YUKKA_UNIVERSE_SOURCE); both are gone.

Reading sentiment from yl-quant's snapshot

Session.sentiment() calls the Data API by default. Live counts are restated as late articles arrive, so two pulls on different days disagree on the same history. Set YUKKA_SENTIMENT_SOURCE=quant_api (optionally YUKKA_SENTIMENT_PULL_DATE) to read the counts yl-quant stored for the STOXX 600 top-200 instead, the same snapshot a strategy run was built on:

from yukka import Session
from yukka.data import Index, set_sentiment_source

set_sentiment_source("quant_api", pull_date="2026-10-01")  # token from YUKKA_TOKEN
with Session() as session:
    df = session.sentiment(Index.STOXX600.assets, date_from="2020-01-01", identifier="ric", t_stat=2.5)

Without a pull_date the latest snapshot is read. sentiment_pull_date() from yukka.data says which one, so it can be recorded next to a result. It is resolved once per process, so every read and the recorded date are the same snapshot. It returns None on the Data API.

The frame and the exclusive date_to are the same as on the Data API. The snapshot is keyed by current RIC and pulled at t_stat=2.5 from 2020-01-01, so other identifiers or thresholds raise instead of returning a different dataset.

Creating assets from different identifier types

from yukka import Session, Asset
from yukka.data import Index

# Explore the universe DataFrame to find identifiers
df = Index.STOXX600.frame

with Session() as session:
    # From YUKKA ID (no API call needed)
    bmw = Asset.from_yukka_id("company:bmw")

    # From ISIN (resolves via Metadata API)
    siemens = Asset.from_isin("DE0007236101")

    # From RIC code (resolves via bundled master file)
    sap = Asset.from_ric("SAPG.DE")

    df = session.sentiment([bmw, siemens, sap], date_from="2026-01-01")

Loading assets from a CSV file

Use Asset.from_csv() to load a universe from a CSV file. The CSV can contain four columns: ric, isin, yukka_id, and proprietary (for your own symbology, e.g., Bloomberg ticker or internal ID):

ric,isin,proprietary
AAPL.OQ,US0378331005,BBG000B9XRY4
SAPG.DE,DE0007164600,BBG000BG7DY8

from yukka import Session, Asset

# CSV must contain a column matching resolve_by ("ric", "isin", or "yukka_id")
assets = Asset.from_csv("my_universe.csv", resolve_by="ric")

# Any additional recognized columns (ric, isin, yukka_id, proprietary) are stored as metadata
# Unresolvable rows emit a warning and are skipped
print(assets[0].proprietary)  # "BBG000B9XRY4"

with Session() as session:
    df = session.sentiment(assets, date_from="2026-01-01")

The resolve_by parameter controls how identifiers are resolved:

• "yukka_id" — used directly, no resolution needed
• "ric" — resolved via the bundled master constituents file
• "isin" — resolved via the bundled constituents files

The proprietary column is always carried through as metadata on the resulting Asset objects, regardless of which resolve_by method is used.

Column names are normalized automatically (case-insensitive and whitespace-trimmed).

Custom identifiers in results

By default, the entity column in sentiment results and event_participant_id in events results contain YUKKA IDs. Use the identifier parameter to replace them with your own symbology:

from yukka import Session, Asset

assets = Asset.from_csv("my_universe.csv", resolve_by="ric")

with Session() as session:
    # Sentiment with RIC codes in the "entity" column
    df = session.sentiment(assets, date_from="2026-01-01", identifier="ric")

    # Events with proprietary IDs in the "event_participant_id" column
    events = session.events(assets, date_from="2026-01-01", identifier="proprietary")

Supported values: "yukka_id" (default), "ric", "isin", "proprietary". When an asset lacks the chosen field, it falls back to the YUKKA ID.

Batch requests

Large entity lists are automatically batched (default 50 per request):

from yukka import Session, Asset
from yukka.data import Index

with Session() as session:
    assets = Asset.from_ric(Index.STOXX600.frame["ric"].to_list())
    df = session.sentiment(assets, date_from="2025-01-01", batch_size=50)

Source Filtering

YUKKA's 241,000+ news sources vary widely in predictive quality. The t_stat parameter filters sources by their t-statistic — a measure of how consistently a source's sentiment predicts forward equity returns, accounting for both signal strength (information ratio) and track-record length. Sources with higher t-statistics carry persistent, non-random explanatory power for cross-sectional returns.

Setting t_stat=2.0 retains roughly 52,000 sources (~35% of articles) and increases the weighted mean IC from 0.006 to 0.035. A threshold of t_stat=2.5 (the paper's recommended default) narrows to ~36,000 sources with a mean IC of 0.041. See the Sentiment Decay & Source Selection white paper for the full methodology:

from yukka import Session, Asset

with Session() as session:
    bmw = Asset.from_yukka_id("company:bmw")
    df = session.sentiment(bmw, date_from="2026-01-01", t_stat=2.0)
    events = session.events(bmw, date_from="2026-01-01", t_stat=2.0)

Note: The pre-validated universe panels were assembled with a forward-looking bias — the full historical constituent list was used to establish the panel, rather than point-in-time membership. Users should be aware of this when running backtests.

Sentiment

Fetch daily sentiment counts (positive / neutral / negative) for one or more assets:

from yukka import Session, Asset

with Session() as session:
    bmw = Asset.from_yukka_id("company:bmw")
    siemens = Asset.from_isin("DE0007236101")

    df = session.sentiment([bmw, siemens], date_from="2026-01-01", date_to="2026-02-01")

Returns a Polars DataFrame with columns: date, entity, positive, neutral, negative.

Events

Fetch event data for assets. The raw response uses numeric event IDs — call .map() to translate them to human-readable names.

from yukka import Session, Asset

with Session() as session:
    bmw = Asset.from_yukka_id("company:bmw")
    siemens = Asset.from_isin("DE0007236101")

    # Raw events — numeric event IDs, factuality codes, and time codes
    events = session.events([bmw, siemens], date_from="2026-01-01", date_to="2026-02-01")

    # Mapped events — human-readable event names, roles, factuality, and temporality
    mapped = events.map()

The .map() method translates numeric codes to human-readable labels:

Universe Coverage

Not all index constituents are present in the YUKKA ontology. The table below summarises coverage by unique ISIN.

License

MIT