yukka 0.6.0

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

Company	YUKKA ID
Amazon	company:amazon_com
Apple	company:apple
ASML	company:asml
Microsoft	company:microsoft
LVMH	company:moet_hennessy_louis_vuitton
Nestlé	company:nestle
Novo Nordisk	company:novo_nordisk
NVIDIA	company:nvidia
SAP	company:sap
Tesla	company:tesla_motors

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.

Offline Mode (no network required)

DummyClient is a fully offline implementation of the same YukkaAPI interface as YukkaClient. It makes no network calls and generates deterministic synthetic data with identical DataFrame schemas, so you can explore the package's shape — for any entity and date range — before requesting a token.

from yukka import DummyClient

# No token, no network — repeated calls return identical frames.
with DummyClient() as client:
    df = client.sentiment(["company:bmw", "company:apple"], "2026-01-01", "2026-01-07")
    events = client.events(["company:bmw"], "2026-01-01", "2026-01-07").map()

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

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

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

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)

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:

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

Universe Coverage

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

Index	Total constituents	In YUKKA ontology	Not in YUKKA ontology	Date range
STOXX 600	1337	1302	35	Oct 2015 – Mar 2026
S&P 500	680	671	9	Jun 2016 – Dec 2025
NASDAQ 100	184	177	7	Jun 2016 – Dec 2025
FTSE 100	126	124	2	Jun 2016 – Dec 2025

STOXX 600 — 35 companies not in YUKKA ontology

RIC	ISIN	Name
1SXP.DE	DE000A3ENQ51	SCHOTT PHARMA
BETSb.ST	SE0006993986	BETSSON B
BORR.OL	BMG1466R1732	BORR DRILLING
CIRSA.MC	ES0105884011	CIRSA ENTERPRISES SAU
COP1n.DE	DE000A288904	COMPUGROUP MEDICAL
DESN.S	CH0582581713	DOTTIKON ES HOLDING
DOU1.DE	DE000BEAU7Y1	DOUGLAS
DOUn.DE	DE000BEAU1Y4	DOUGLAS
EXENS.PA	FR001400Q9V2	EXOSENS
EXN.PA	FR0014005DA7	EXCLUSIVE NET PROM
FIA1S.HE	FI4000567029	FINNAIR
FRAMERY.HE	FI4000595756	FRAMERY GROUP
GRK.HE	FI4000517966	GRK INFRA
GUBRA.CO	DK0062266474	GUBRA
HLUNb.CO	DK0061804770	H. LUNDBECK B
HSHP.OL	BMG4660A1036	HIMALAYA SHIPPING
ICP.L	GB00BYY5B507	INTERMEDIATE CAPITAL GRP
KALMAR.HE	FI4000571054	KALMAR
KEMPOWR.HE	FI4000513593	KEMPOWER
KWE.L	JE00BJT32513	KENNEDY WILSON EU.RLST.
LUKN.S	CH1252930610	LUZERNER KANTONALBANK
NTGNT.CO	DK0061141215	NTG NORDIC TRANSPORT GROUP
OBCK.DE	DE000BCK2223	OTTOBOCK
PLNW.PA	FR001400PFU4	PLANISWARE
PPGN.S	CH1110760852	POLYPEPTIDE N
RSGN.S	CH1107979838	R&S GROUP HOLDING AG
SHA0.DE	DE000SHA0019	SCHAEFFLER AG
SHA0n.DE	DE000SHA0100	SCHAEFFLER AG
SMGC.S	CH1484953687	SMG
STM1.DE	DE000STAB1L8	STABILUS
SVITZR.CO	DK0062616637	SVITZER
SWTQ.S	CH1248667003	SCHWEITER TECHNOLOGIES
TKMS.DE	DE000TKMS001	TKMS
VIRI.PA	FR001400PVN6	VIRIDIEN
YOUG.DE	DE000A3CNK42	ABOUT YOU HOLDING

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