Documentation → Screening and scoring

Documentation

Screening and scoring

Persisted scores, peer groups and percentiles.

What it is good for is on the product page: Screening and scoring

GET/analysis/earningsGET/analysis/earnings/isin-qualityGET/analysis/ticker-reference/missing-isinGET/performance/peer-comparison/{identifier}GET/scoringPOST/scoring/batchGET/scoring/compare/{level}/{group_id}GET/scoring/jobs/{job_id}GET/scoring/peers/{ticker}POST/scoring/percentilesPOST/scoring/price-cache/refreshGET/scoring/{ticker}

GET /analysis/earnings

Earnings Analysis

Aggregate statistics over all tickers in the earnings MongoDB cache.

by_country — requires tickers to have been fetched with origin=yf or

origin=all (yfinance.info provides country metadata).

upcoming_earnings — dates ≤ 90 days in the future with confidence ≥ 0.6.
stale_tickers — entries where fetched_at is > 7 days ago.

No parameters.

Example

curl "$API/analysis/earnings" \
  -H "X-API-Key: $KEY"

GET /analysis/earnings/isin-quality

Earnings Isin Quality

Quality overview for the ISIN-based earnings sync scope.

The scope matches ticker_reference entries that:

have a non-empty isin
belong to the requested type_filters
are market='stocks' and active=True

Name	Type	Meaning
`type_filters`	array, in query optional · default `['CS', 'ADRC']`	—
`include_untyped_stocks`	boolean, in query optional · default `False`	—

Example

curl "$API/analysis/earnings/isin-quality" \
  -H "X-API-Key: $KEY"

GET /analysis/ticker-reference/missing-isin

Missing Isin Analysis

Analyse the ticker_reference collection for entries with market='stocks' that have no ISIN (field absent, null, or empty string).

Returns the total count of stocks, how many lack an ISIN, and the full list of affected tickers.

No parameters.

Example

curl "$API/analysis/ticker-reference/missing-isin" \
  -H "X-API-Key: $KEY"

GET /performance/peer-comparison/{identifier}

Peer Comparison

One stock against its peer group over a window.

Reads only from price_history; when no bars exist there for the security or the group, coverage says so explicitly — a group must never look complete when it is not.

Name	Type	Meaning
`identifier`	string, in path required	—
`level`	string, in query optional · default `branch`	branch = onvista-Branche (76, Median 116 Unternehmen), sector = Sektor (16, deutlich grober)
`window`	string, in query optional · default `7d`	eines von ['14d', '1d', '1m', '1w', '1y', '3m', '6m', '7d', 'ytd']
`weighting`	string, in query optional · default `market_cap`	—
`currency`	string, in query optional · default `EUR`	—
`exclude_self`	boolean, in query optional · default `True`	den Titel selbst aus der Gruppe nehmen
`min_market_cap`	number, in query optional · default `5000000000.0`	Untergrenze für die Ausreißer-Nennung
`min_trading_days`	integer, in query optional · default `5`	Reihen mit weniger Handelstagen im Fenster gelten als zu dünn
`max_drivers`	integer, in query optional · default `3`	—
`max_outliers`	integer, in query optional · default `3`	—

Example

curl "$API/performance/peer-comparison/SAP" \
  -H "X-API-Key: $KEY"

GET /scoring

Scoring Screener

Screener over the persisted scores (stock_scores) — filtered, sorted, paginated. Returns the flat metrics, without full detail.

Name	Type	Meaning
`min_chance`	number, in query optional	—
`max_risk`	number, in query optional	—
`confidence`	string, in query optional	high \| medium \| low
`source`	string, in query optional	onvista \| sec_xbrl
`sort_by`	string, in query optional · default `chance`	chance \| risk \| data_quality
`limit`	integer, in query optional · default `100`	—
`offset`	integer, in query optional · default `0`	—

Example

curl "$API/scoring" \
  -H "X-API-Key: $KEY"

POST /scoring/batch

Scoring Batch

Computes the opportunity/risk profiles for the entire addressable universe (~11k) and persists them into stock_scores. Background job — progress via GET /scoring/jobs/{job_id}. Without yfinance (the valuation pillar for XBRL-only securities is filled later by the price cache).

Name	Type	Meaning
`limit`	integer, in query optional	max. Titel (Test)

Example

curl -X POST "$API/scoring/batch" \
  -H "X-API-Key: $KEY"

GET /scoring/compare/{level}/{group_id}

Scoring Compare

Compares every company in a taxonomy peer group by its opportunity and risk scores. level: grandparent | parent | keyword; group_id for example product:cloud_platform (grandparent), product:security_cloud (parent) or saas_subscription_model (keyword).

Returns group statistics (median, mean and quartiles for opportunity and risk) and the members with their within-group percentile (chance_percentile_in_group, risk_percentile_in_group). Computed on demand from the persisted scores.

Name	Type	Meaning
`level`	string, in path required	—
`group_id`	string, in path required	—
`min_confidence`	string, in query optional	high \| medium \| low — nur mind. diese Konfidenz
`sort`	string, in query optional · default `chance_desc`	chance_desc \| chance_asc \| risk_desc \| risk_asc
`dedup`	boolean, in query optional · default `True`	Mehrfachnotierungen desselben Unternehmens (company_id) zusammenfassen
`limit`	integer, in query optional	max. Ergebnisse (leer = vollständige Liste)

Example

curl "$API/scoring/compare/grandparent/SAP" \
  -H "X-API-Key: $KEY"

GET /scoring/jobs/{job_id}

Scoring Job Status

Name	Type	Meaning
`job_id`	string, in path required	—

Example

curl "$API/scoring/jobs/job_7f3c" \
  -H "X-API-Key: $KEY"

GET /scoring/peers/{ticker}

Scoring Peers

Where does a ticker sit in its taxonomy peer groups? For each group (parent and grandparent) the ticker's within-group opportunity and risk percentile plus the group median. Additionally the already persisted sector percentile as a universal fallback.

Grandparent groups are restricted by default to coherent / approved clusters (draft clusters lump unrelated themes together); parent groups stay as they are (fine-grained, reliable). include_incoherent=true shows all.

Name	Type	Meaning
`ticker`	string, in path required	—
`all_tags`	boolean, in query optional · default `False`	auch nicht-vergleichsrelevante Tag-Arten (geography, financial_metric, …)
`include_incoherent`	boolean, in query optional · default `False`	auch draft/nicht-kohärente Grandparent-Cluster einbeziehen
`min_scored`	integer, in query optional · default `3`	Mindestzahl gescorter Peers je Gruppe

Example

curl "$API/scoring/peers/SAP" \
  -H "X-API-Key: $KEY"

POST /scoring/percentiles

Scoring Percentiles

Computes peer percentiles (universe-wide and per sector) over the persisted scores and writes them back. Run after /scoring/batch. chance_percentile (higher is better), risk_percentile (lower is better).

No parameters.

Example

curl -X POST "$API/scoring/percentiles" \
  -H "X-API-Key: $KEY"

POST /scoring/price-cache/refresh

Refresh Price Cache

Fills the price cache for all XBRL securities that have a share count (~4,900) via a yfinance batch — the precondition for the batch score to fill the valuation pillar for SEC-only securities too. Background job; run /scoring/batch again afterwards.

Name	Type	Meaning
`limit`	integer, in query optional	—

Example

curl -X POST "$API/scoring/price-cache/refresh" \
  -H "X-API-Key: $KEY"

GET /scoring/{ticker}

Stock Score

Fundamental opportunity/risk profile (phase 1a, absolute) for a ticker.

Computed live (including the yfinance price for XBRL securities). ?stored=true returns the most recently persisted batch score instead.

Name	Type	Meaning
`ticker`	string, in path required	—
`stored`	boolean, in query optional · default `False`	persistierten Score liefern statt live rechnen

Example

curl "$API/scoring/SAP" \
  -H "X-API-Key: $KEY"