yukka 0.2.2

Wrapper around Yukka APIs for getting easy access to quantitative insights

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 stoxx600

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

Installation

pip install yukka

Requires Python 3.13+.

Authentication

Contact YUKKA Lab to request API token access.

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

The package ships with pre-resolved constituent lists for major indices. No entity resolution needed.

from yukka import Session, Asset
from yukka.data import stoxx600, sp500, ftse100, nasdaq100

# Load STOXX 600 constituents (isin, ric, name, yukka_id, ...)
universe = stoxx600()

# 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")

Creating assets from different identifier types

from yukka import Session, Asset

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", session.resolver)

    # 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")

Batch requests

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

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

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", session.resolver)

    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", session.resolver)

    # 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:

factuality codes

Code	Label
0	fact
1	counterfact
2	possible
3	counterpossible
4	probable
5	counterprobable
6	unknown
7	none

time codes

Code	Label
0	past
1	present
2	future
3	unknown
4	none

event_id codes

Code	Event
E1_A	QF Reporting Growth
E1_B	QF Reporting Drop
E1_C	QF Announcement
E2_A	Product Launch
E2_B	Product Cancellation/Delay
E2_C	Product Launch Announcement
E3_A	Product Recall
E5_A	Market Expansion
E6_A	Merger
E6_B	Acquisition
E6_C	Share Purchase
E6_D	Share Sell
E6_E	Company Sell
E6_F	Company Spin-off
E7_A	IPO Announcement
E7_B	IPO
E7_C	IPO Cancellation/Delay
E8_A	C-Level Departure
E8_B	C-Level Appointment
E8_C	C-Level Search
E9_A	Sales Volume Increase
E9_B	Sales Volume Decrease
E10_A	Production Increase
E10_B	Production Decrease
E11_A	Profit Warning
E12_A	Capital Increase
E12_B	Capital Decrease
E13_A	Restructure/Job Cuts
E13_B	Short-Time Work
E14_A	Trade Sanctions
E14_B	Sanctions
E15_A	Supply Chain Problems
E16_A	Insider Trading Violation
E16_B	Legal Insider Trading
E17_A	Cyber Attack
E17_B	Cyber Defence
E17_C	Data Breach
E17_D	Data Security Improvement
E18_A	Bankruptcy
E18_B	Insolvency
E18_C	Liquidity
E18_G	Strengthen Liquidity
E19_A	Joint Venture
E19_B	Strategic Alliance
E20_A	Money Laundering
E21_A	Tax Evasion
E21_B	Tax Transparency
E22_A	Forgery
E22_B	Corruption
E22_C	Bribery
E23_A	Terrorism Financing
E23_B	Recession
E23_C	Economic Crisis
E23_D	Economic Recovery
E24_A	Coal Plant Opening
E24_B	Coal Plant Retirement
E24_C	Coal Plant Cancellation
E25_A	Environmental Regulations
E25_B	Environmental Regulation Violation
E25_C	Positive CO2 Regulations
E25_D	Negative CO2 Regulations
E25_E	CO2 Regulation Violation
E26_A	Currency Trading: Up
E26_B	Currency Trading: Down
E27_A	Long Bets Increase
E27_B	Long Bets Decrease
E27_C	Short Bets Increase
E27_D	Short Bets Decrease
E28_A	Dissociation of State
E29_A	Civil Unrest
E29_B	Homelessness
E30_A	War
E31_A	Election Lost
E31_B	Election Won
E32_A	Negative Climate Change
E32_C	Greenwashing
E32_D	Natural Disaster
E33_A	CO2 Emissions
E33_B	Decarbonisation
E33_C	Portfolio Decarbonisation
E33_D	Fossil Fuels Usage
E33_E	Fossil Fuels Divestment
E33_F	Reporting Product Carbon Footprint
E33_G	Carbon Footprint Reporting
E33_H	Scope 1 & 2 Emissions Reduction
E33_I	Scope 3 Emission Reduction
E33_J	Carbon Offset Trading
E33_K	Direct Carbon Offset
E33_L	Carbon Capture Technology
E34_A	Energy Efficiency
E34_B	Alternative Energy Development
E34_C	Clean Technology Development
E34_D	Waste Treatment/Recycling
E34_E	Green Steel Development
E34_F	Sustainable Material Solutions
E35_A	Grounded Fleet
E35_B	Plant Closure
E35_C	Plant (Re-)Opening
E36_A	Border Closed
E36_B	Curfew
E37_A	Target Price Upgrade
E37_B	Target Price Downgrade
E37_C	Target Price
E38_A	Buy Rating
E38_B	Sell Rating
E38_C	Hold Rating
E38_D	Rating Upgrade
E38_E	Rating Downgrade
E39_A	Sell List Deletion
E39_B	Buy List Deletion
E41_A	Stock Price Up
E41_B	Stock Price Down
E41_C	Short-Seller Attack
E42_A	Reorganization
E42_B	Credits Not Serviced
E45_A	Asset Stripping
E45_B	Blacklisted
E45_C	Strategic Expenditure Cut
E46_A	Food Insecurity
E46_B	Sustainable Food
E46_C	Sustainable Farming
E47_A	Unethical Business Activity
E48_A	Forced Labour
E48_B	Supply Chain Controversies
E48_C	Workers' Strikes
E48_D	Minimum Wage Increase
E48_E	Unemployment
E48_F	Workplace Equality
E48_G	Workplace Discrimination
E48_H	Industrial Accident
E48_I	Explosion
E49_A	Water Pollution
E49_B	Water Stewardship
E49_C	Water Stress
E50_A	Lobbying for Good
E50_B	Lobbying for Bad
E51_A	Human Rights Violation
E51_B	Educational Access
E51_C	No Educational Access
E51_D	Healthcare Access
E51_E	No Healthcare Access
E52_A	Biodiversity Protection
E52_B	Biodiversity Loss
E53_A	Lawsuit
E53_B	Investigation
E54_A	Margin Call
E55_A	Fine
E56_A	Patent Application

event_participant_role codes (per event)

Event	Role	Label
E1_A	P1	Increasing Participant
E1_B	P1	Decreasing Participant
E1_C	P1	Company
E2_A	P1, P2	Company, Product
E2_B	P1, P2	Company, Product
E2_C	P1, P2	Company, Product
E3_A	P1, P2	Company, Product
E5_A	P1, P2	Company, Location
E6_A	P1	Company
E6_B	P1, P2	Acquirer, Acquired
E6_C	P1, P2, P3	Acquirer, Acquired, Amount
E6_D	P1, P2, P3, P4	Seller, Sold, Acquirer, Amount
E6_E	P1, P2, P3, P4	Seller, Sold, Acquirer, Amount
E6_F	P1, P2	Parent Company, Spun-off Company
E7_A	P1, P2, P3	Company, Stock Exchange, Date
E7_B	P1, P2, P3	Company, Stock Exchange, Date
E7_C	P1, P2, P3	Company, Stock Exchange, Date
E8_A	P1, P2	Company, Person
E8_B	P1, P2	Company, Person
E8_C	P1	Company
E9_A	P1, P2, P3	Increasing Participant, Amount, Location
E9_B	P1, P2, P3	Decreasing Participant, Amount, Location
E10_A	P1, P2, P3, P4	Company, Product, Amount, Location
E10_B	P1, P2, P3, P4	Company, Product, Amount, Location
E11_A	P1	Company
E12_A	P1, P2	Company, Amount
E12_B	P1, P2	Company, Amount
E13_A	P1, P2	Employer, Amount
E13_B	P1, P2	Work Reducer, Date
E14_A	P1, P2	Sanctioner, Sanctioned
E14_B	P1, P2	Sanctioner, Sanctioned
E15_A	P1, P2	Company, Product
E16_A	P1	Perpetrator
E16_B	P1, P2, P3	Trader, Company, Amount
E17_A	P1, P2	Attacker, Attacked
E17_B	P1, P2	Defender, Perpetrator
E17_C	P1, P2	Attacker, Attacked
E17_D	P1	Data Security Improver
E18_A	P1	Bankrupt
E18_B	P1	Insolvent
E18_C	P1	Illiquid
E18_G	P1	Strenghtener
E19_A	P1	Company
E19_B	P1	Company
E20_A	P1	Perpetrator
E21_A	P1	Perpetrator
E21_B	P1, P2	Tax Transparency Supporter, Tax Payer
E22_A	P1	Perpetrator
E22_B	P1	Perpetrator
E22_C	P1, P2, P3	Perpetrator, Bribed, Amount
E23_A	P1, P2	Perpetrator, Financed
E23_B	P1	Affected By Recession
E23_C	P1	Affected by Economic Crisis
E23_D	P1	Recoverer
E24_A	P1, P2	Constructor, Location
E24_B	P1, P2	Closing Party, Location
E24_C	P1, P2	Cancellator, Location
E25_A	P1	Regulator
E25_B	P1, P2	Perpetrator, Location
E25_C	P1	Affected Party
E25_D	P1	Affected Party
E25_E	P1, P2	Perpetrator, Location
E26_A	P1, P2, P3	Rising Currency, Falling Currency, Amount
E26_B	P1, P2, P3	Falling Currency, Rising Currency, Amount
E27_A	P1, P2	Currency, Amount
E27_B	P1, P2	Currency, Amount
E27_C	P1, P2	Currency, Amount
E27_D	P1, P2	Currency, Amount
E28_A	P1, P2, P3	Separatist, Abandoned Party, Date
E29_A	P1	Location
E29_B	P1, P2	Location, Amount
E30_A	P1	War Participant
E31_A	P1, P2, P3	Loser, Amount, Location
E31_B	P1, P2, P3	Winner, Amount, Location
E32_A	P1, P2	Perpetrator, Victim
E32_C	P1	Greenwasher
E33_A	P1, P2, P3	Emitter, Location, Amount
E33_B	P1, P2, P3	CO2 Reducer, Location, Amount
E33_C	P1	Portfolio Holder
E33_D	P1, P2, P3	Perpetrator, Location, Amount
E33_E	P1	Divestor
E33_F	P1, P2	Product Carbon Footprint Reporter, Product
E33_G	P1	Carbon Footprint Reporter
E33_H	P1, P2	Reducer, Amount
E33_I	P1, P2	Reducer, Amount
E33_J	P1, P2	Offsetter, Seller
E33_K	P1	Offsetter
E33_L	P1	Carbon Capture Technology Enthusiast
E34_A	P1, P2	Reducer, Amount
E34_B	P1, P2	Utility, Location
E34_C	P1	Clean Technology Enthusiast
E34_D	P1, P2, P3	Waste Manager, Amount, Location
E34_E	P1, P2	Enthusiast, Location
E34_F	P1	Sustainable Material Solutions
E35_A	P1, P2, P3, P4	Cancelling Party, Location, Amount, Date
E35_B	P1, P2	Plant Closer, Date
E35_C	P1, P2	Plant Re/Opener, Location
E36_A	P1, P2, P3	Closer, Affected by Border Closure, Date
E36_B	P1, P2, P3	Curfew Imposer, Affected by Curfew, Date
E37_A	P1, P2, P3	Analyst, Rated Company, Amount
E37_B	P1, P2, P3	Analyst, Rated Company, Amount
E37_C	P1, P2, P3	Analyst, Rated Company, Amount
E38_A	P1, P2	Analyst, Rated Company
E38_B	P1, P2	Analyst, Rated Company
E38_C	P1, P2	Analyst, Rated Company
E38_D	P1, P2	Analyst, Rated Company
E38_E	P1, P2	Analyst, Rated Company
E39_A	P1, P2	List Holder, List Company
E39_B	P1, P2	List Holder, List Company
E41_A	P1, P2	Shares, Amount
E41_B	P1, P2	Shares, Amount
E41_C	P1, P2	Attacked, Attacker
E42_A	P1	Reorganizer
E42_B	P1	Affected by Credit Problems
E45_A	P1, P2	Stripper, Stripped
E45_B	P1, P2	Blacklister, Blacklisted
E45_C	P1	Reducer
E46_A	P1, P2	Food Insecurity, Amount
E46_B	P1	Experiencer
E46_C	P1	Sustainable Farmer
E47_A	P1	Unethical Party
E48_A	P1, P2	Forcing Party, Location
E48_B	P1, P2	Violator, Location
E48_C	P1, P2	Strike Affiliate, Location
E48_D	P1, P2, P3	Executor, Amount, Date
E48_E	P1, P2	Unemployed, Amount
E48_F	P1	Fair Workplace
E48_G	P1, P2	Discriminator, Discriminated
E48_H	P1	Affected Party
E48_I	P1	Explosion
E49_A	P1	Polluted
E49_B	P1	Steward of water
E49_C	P1, P2	Water Stressed, Amount
E50_A	P1, P2	Lobbyist, Location
E50_B	P1, P2	Lobbyist, Location
E51_A	P1	Perpetrator
E51_B	P1, P2	Improver, Location
E51_C	P1, P2	Affected Side, Amount
E51_D	P1	Improver
E51_E	P1	Affected Side
E52_A	P1, P2	Protector, Location
E52_B	P1	Affected by Biodiversity Loss
E53_A	P1, P2	Plaintiff, Defendant
E53_B	P1, P2	Investigated, Investigator
E54_A	P1, P2	Affected Party, Broker
E55_A	P1, P2, P3	Imposer, Fined, Amount
E56_A	P1	Patent Application

API Reference

Session

High-level entry point. Reads YUKKA_TOKEN from the environment automatically.

Method	Description
session.sentiment(assets, date_from, date_to)	Fetch daily sentiment counts (positive / neutral / negative)
session.events(assets, date_from, date_to)	Fetch events; returns EventsFrame — call .map() for human-readable labels
session.event_names()	Dict of event ID → name (e.g. {"E6_B": "Acquisition"})
session.resolver	EntityResolver for ISIN → YUKKA ID lookups
session.today	Today's date

Asset

Immutable representation of a YUKKA entity.

Factory	Description
Asset.from_yukka_id(id)	From a YUKKA compound key, e.g. "company:bmw"
Asset.from_isin(isin, resolver)	From an ISIN via Metadata API lookup
Asset.from_ric(ric)	From a RIC code via bundled master file

All factory methods accept a single value or a list.

YukkaClient

Low-level client for direct API access, if you need more control than Session provides.

from yukka import YukkaClient

with YukkaClient.from_token("eyJ...") as client:
    df = client.sentiment(["company:bmw", "company:siemens"], "2026-01-01", "2026-01-31")

Pre-validated universes

from yukka.data import stoxx600, sp500, ftse100, nasdaq100

df = stoxx600()   # STOXX Europe 600
df = sp500()      # S&P 500
df = ftse100()    # FTSE 100
df = nasdaq100()  # NASDAQ 100

Each returns a Polars DataFrame with isin, constituent_ric, constituent_name, and yukka_id columns.

Universe Coverage

Not all index constituents are present in the YUKKA ontology. The table below summarises coverage as of the bundled master file.

Index	Total constituents	In YUKKA ontology	Not in YUKKA ontology
STOXX 600	931	915	16
S&P 500	680	671	9
NASDAQ 100	184	177	7
FTSE 100	126	124	2

Each list contains historical constituents from June 2016 to December 2025.

STOXX 600 — 16 companies not in YUKKA ontology

RIC	ISIN	Name
SAB.L^J16	GB00BYZTBD95	Abi Sab Group Holding Ltd
AMRZ.S	CH1430134226	Amrize AG
CVC.AS	JE00BRX98089	CVC Capital Partners PLC
CAN.L	FR001400T0D6	Canal+ SA
EMEIS.PA	FR001400NLM4	Emeis SA
GALD.S	CH1335392721	Galderma Group Ltd
HIAB.HE	FI4000571013	Hiab Oyj
LTMC.MI	IT0005541336	Lottomatica Group SpA
MFEB.MI	NL0015001OJ9	MFE-MEDIAFOREUROPE NV
MICCT.L	NL0015002MS2	Magnum Ice Cream Company NV
PUIGb.MC	ES0105777017	Puig Brands SA
R3NK.DE	DE000RENK730	RENK Group AG
SUNN.S	CH1386220409	Sunrise Communications AG
VAR.OL	NO0011202772	Var Energi ASA
VSURE.ST	GB00BVMN1558	Verisure PLC
VOLCARb.ST	SE0021628898	Volvo Car AB

S&P 500 — 9 companies not in YUKKA ontology

RIC	ISIN	Name
AMCR.N	JE00BV7DQ550	Amcor PLC
AMTM.N	US0239391016	Amentum Holdings Inc
J.N	US46982L1089	Jacobs Solutions Inc
LH.N	US5049221055	Labcorp Holdings Inc
PSKY.OQ	US69932A2042	Paramount Skydance Corp
Q.N	US74743L1008	Qnity Electronics Inc
SOLV.N	US83444M1018	Solventum Corp
TEL.N	IE000IVNQZ81	TE Connectivity PLC
TKO.N	US87256C1018	TKO Group Holdings Inc

NASDAQ 100 — 7 companies not in YUKKA ontology

RIC	ISIN	Name
ARM.OQ	US0420682058	Arm Holdings PLC
GRAL.OQ	US3847471014	Grail Inc
LBTYA.OQ	BMG611881019	Liberty Global Ltd
LCID.OQ	US5494982029	Lucid Group Inc
QVCGA.OQ	US74915M6057	QVC Group Inc
SIRI.OQ	US8299331004	Sirius XM Holdings Inc
TRI.OQ	CA8849038085	Thomson Reuters Corp

FTSE 100 — 2 companies not in YUKKA ontology

RIC	ISIN	Name
BMEB.L	JE00BVSYJW51	B&M European Value Retail SA
PCT.L	GB00BR3YV268	Polar Capital Technology Trust PLC

License

MIT