Dokumentation → Thematische Taxonomie

Dokumentation

Thematische Taxonomie

Drei Ebenen: Schlagwort, Thema, Oberkategorie.

Wozu das gut ist, steht auf der Produktseite: Thematische Taxonomie

GET/taxonomy/by-parent/{parent_id}GET/taxonomy/grandparentsPOST/taxonomy/grandparents/bulkPOST/taxonomy/grandparents/move-parentsGET/taxonomy/grandparents/{grandparent_id}PATCH/taxonomy/grandparents/{grandparent_id}GET/taxonomy/keyword/{keyword_id}GET/taxonomy/keywords/resolveGET/taxonomy/parentsGET/taxonomy/parents/{parent_id}/keywordsPOST/taxonomy/review/bulkGET/taxonomy/review/logGET/taxonomy/review/progressGET/taxonomy/review/queuePOST/taxonomy/review/undoPOST/taxonomy/review/{keyword_id}GET/taxonomy/statsGET/taxonomy/stock/{stock_id}

GET /taxonomy/by-parent/{parent_id}

Stocks By Parent

Alle Aktien unter einem Parent bzw. Grandparent.

group=listing (Default) ist der bisherige Peer-Vergleich: rohe Zeilen aus kw_taxonomy_stock. Bestehende Konsumenten bleiben unberuehrt.

group=company liefert dieselbe Struktur wie /tickers/by-keyword -- Unternehmen statt Notierungen, mit primary, listings, tickers, isins und market_cap. Damit fuehrt ein Klick auf ein Thema in der Trefferliste zu genau derselben Ergebnisdarstellung wie die Themensuche, ohne dass das Frontend einen zweiten Renderer braucht.

Name	Typ	Bedeutung
`parent_id`	string, im Pfad Pflicht	—
`level`	string, in der Abfrage optional · Vorgabe `parent`	—
`group`	string, in der Abfrage optional · Vorgabe `listing`	listing = rohe Tag-Zeilen (Default, unveraendert); company = Trefferliste wie /tickers/by-keyword
`active`	boolean, in der Abfrage optional	nur aktive/inaktive Titel (nur bei group=company)
`sort`	string, in der Abfrage optional · Vorgabe `relevance`	relevance = staerkste Themenzuordnung zuerst; market_cap = groesste Marktkapitalisierung zuerst
`limit`	integer, in der Abfrage optional · Vorgabe `200`	—
`offset`	integer, in der Abfrage optional · Vorgabe `0`	—

Beispiel

curl "$API/taxonomy/by-parent/482" \
  -H "X-API-Key: $KEY"

GET /taxonomy/grandparents

List Grandparents

Grobe Ebene (~300 Kategorien). Labels aus der kuratierten Registry (kw_taxonomy_grandparents), falls vorhanden; sonst Fallback-Aggregation.

Name	Typ	Bedeutung
`tag_type`	string, in der Abfrage optional	—
`status`	string, in der Abfrage optional	draft\|approved\|frozen
`limit`	integer, in der Abfrage optional · Vorgabe `500`	—

Beispiel

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

POST /taxonomy/grandparents/bulk

Grandparent Bulk

Massenaktionen wie review_taxonomy.py gp-bulk, nur aus der Oberfläche: kohärente Gruppen freigeben bzw. freigegebene einfrieren.

Keine Parameter.

Anfragekörper `GrandparentBulk`

Name	Typ	Bedeutung
`action`	string Pflicht	Action
`tag_type`	string optional	Tag Type
`reviewer`	string optional	Reviewer
`dry_run`	boolean optional · Vorgabe `True`	Dry Run

Beispiel

curl -X POST "$API/taxonomy/grandparents/bulk" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

POST /taxonomy/grandparents/move-parents

Move Parents

Parents unter einen anderen Grandparent hängen — das Werkzeug gegen die Ward-Artefakte (einzelne Ausreißer in einer sonst sauberen Gruppe).

Zusammenführen zweier Grandparents ist derselbe Vorgang mit allen Parents der Quelle. Schreibt in drei Collections, weil grandparent_id in kw_taxonomy_map und kw_taxonomy_stock denormalisiert liegt — würde nur die Registry geändert, liefen Peer-Abfragen auf by-parent?level=grandparent weiter auf den alten Wert.

Keine Parameter.

Anfragekörper `MoveParents`

Name	Typ	Bedeutung
`parent_ids`	array Pflicht	Parent Ids
`target_grandparent_id`	string Pflicht	Target Grandparent Id
`reviewer`	string optional	Reviewer
`dry_run`	boolean optional · Vorgabe `True`	Dry Run

Beispiel

curl -X POST "$API/taxonomy/grandparents/move-parents" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

GET /taxonomy/grandparents/{grandparent_id}

Grandparent Detail

Ein Grandparent mit seinen feinen Parents (aus der Registry).

Name	Typ	Bedeutung
`grandparent_id`	string, im Pfad Pflicht	—

Beispiel

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

PATCH /taxonomy/grandparents/{grandparent_id}

Patch Grandparent

Label (6 Sprachen), Status und Notiz eines Grandparents ändern.

Die Registry ist die maßgebliche Label-Quelle — die großen Collections joinen per grandparent_id, ein Label-Fix wirkt also sofort überall.

Name	Typ	Bedeutung
`grandparent_id`	string, im Pfad Pflicht	—

Anfragekörper `GrandparentPatch`

Name	Typ	Bedeutung
`labels`	object optional	Labels
`status`	string optional	Status
`coherent`	boolean optional	Coherent
`note`	string optional	Note
`reviewer`	string optional	Reviewer

Beispiel

curl -X PATCH "$API/taxonomy/grandparents/SAP" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

GET /taxonomy/keyword/{keyword_id}

Keyword Mapping

Gegenrichtung zu /parents/{parent_id}/keywords: von EINEM Keyword nach oben auf Parent und Grandparent schließen.

keyword_id ist dieselbe ID wie in /tickers/keywords bzw. in keywords_multilingual.keyword_id — jedes Keyword hat genau ein Mapping. status beachten: needs_review heißt maschinell geclustert und nicht bestätigt; candidates zeigt die Alternativen mit Score.

Beispiel: /taxonomy/keyword/cybersecurity → industry:cybersecurity.

Name	Typ	Bedeutung
`keyword_id`	string, im Pfad Pflicht	—

Beispiel

curl "$API/taxonomy/keyword/12345" \
  -H "X-API-Key: $KEY"

GET /taxonomy/keywords/resolve

Resolve Keywords

Batch-Variante: viele Keywords in EINEM Call auf ihre Parents auflösen — damit ein Client die Keyword-Liste einer Aktie nicht Keyword für Keyword abfragen muss. Nicht gemappte IDs fehlen in der Antwort (kein 404).

Name	Typ	Bedeutung
`ids`	string, in der Abfrage Pflicht	Komma-getrennte keyword_ids, max. 500

Beispiel

curl "$API/taxonomy/keywords/resolve?ids=SAP" \
  -H "X-API-Key: $KEY"

GET /taxonomy/parents

List Parents

Feine Ebene (~7.000 Parents).

Name	Typ	Bedeutung
`tag_type`	string, in der Abfrage optional	—
`grandparent_id`	string, in der Abfrage optional	—
`search`	string, in der Abfrage optional	Filtert label_en/label_de
`limit`	integer, in der Abfrage optional · Vorgabe `200`	—

Beispiel

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

GET /taxonomy/parents/{parent_id}/keywords

Parent Keywords

Alle Detail-Keywords, die auf diesen Parent gemappt sind.

Name	Typ	Bedeutung
`parent_id`	string, im Pfad Pflicht	—
`limit`	integer, in der Abfrage optional · Vorgabe `500`	—

Beispiel

curl "$API/taxonomy/parents/482/keywords" \
  -H "X-API-Key: $KEY"

POST /taxonomy/review/bulk

Review Bulk

Viele Fälle auf einmal entscheiden (nur approve/reject — ein Sammel-Reassign auf EINEN Parent wäre fast immer falsch).

Läuft per Default als dry_run und meldet nur, wie viele betroffen wären. Erst dry_run=false schreibt. Der Vorzustand landet vollständig im Log, die Aktion ist über batch_id als Ganzes zurücknehmbar.

Keine Parameter.

Anfragekörper `BulkReview`

Name	Typ	Bedeutung
`verdict`	string optional · Vorgabe `approve`	Verdict
`tag_type`	string optional	Tag Type
`ranks`	string optional	Ranks
`min_count`	integer optional · Vorgabe `0`	Min Count
`self_named`	boolean optional	Self Named
`llm_agrees`	boolean optional	nur Fälle, in denen der LLM-Vorschlag die Pipeline bestätigt
`min_llm_confidence`	number optional · Vorgabe `0.0`	Min Llm Confidence
`keyword_ids`	array optional	Keyword Ids
`reviewer`	string optional	Reviewer
`limit`	integer optional · Vorgabe `5000`	Limit
`dry_run`	boolean optional · Vorgabe `True`	Dry Run

Beispiel

curl -X POST "$API/taxonomy/review/bulk" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

GET /taxonomy/review/log

Review Log

Was wurde zuletzt entschieden (neueste zuerst).

Name	Typ	Bedeutung
`scope`	string, in der Abfrage optional	—
`batch_id`	string, in der Abfrage optional	—
`limit`	integer, in der Abfrage optional · Vorgabe `50`	—

Beispiel

curl "$API/taxonomy/review/log" \
  -H "X-API-Key: $KEY"

GET /taxonomy/review/progress

Review Progress

Kopfzeile der Oberfläche: was ist offen, was ist geschafft.

Getrennt nach den beiden Ebenen, weil sie unterschiedlich groß sind und unterschiedlich viel bewirken.

Keine Parameter.

Beispiel

curl "$API/taxonomy/review/progress" \
  -H "X-API-Key: $KEY"

GET /taxonomy/review/queue

Review Queue

Offene Keyword-Fälle, wichtigste zuerst (Rang, dann Aktien-Anzahl).

Anders als eine reine Score-Sortierung stellt das die Fälle nach vorn, bei denen eine Fehlentscheidung tatsächlich etwas verschiebt. ranks=all liefert weiterhin die vollständige Menge.

Name	Typ	Bedeutung
`tag_type`	string, in der Abfrage optional	—
`ranks`	string, in der Abfrage optional · Vorgabe `0`	review_rank-Filter, komma-separiert. 0=echte Entscheidung … 3=nicht vergleichsrelevant. 'all' = ohne Filter
`min_count`	integer, in der Abfrage optional · Vorgabe `0`	nur Keywords ab N Aktien
`self_named`	boolean, in der Abfrage optional	nur/keine Namensgeber-Fälle
`has_llm`	boolean, in der Abfrage optional	nur Fälle mit LLM-Vorschlag
`llm_disagrees`	boolean, in der Abfrage optional	nur wo LLM != Pipeline-Top-1
`search`	string, in der Abfrage optional	Volltext auf Label/ID
`skip`	integer, in der Abfrage optional · Vorgabe `0`	—
`limit`	integer, in der Abfrage optional · Vorgabe `50`	—
`min_score`	number, in der Abfrage optional · Vorgabe `0.0`	—

Beispiel

curl "$API/taxonomy/review/queue" \
  -H "X-API-Key: $KEY"

POST /taxonomy/review/undo

Review Undo

Eine Entscheidung oder eine ganze Massen-Aktion zurücknehmen.

Spielt den im Log festgehaltenen Vorzustand zurück. Felder, die es vorher nicht gab (reviewed_at beim ersten Review), werden entfernt statt auf null gesetzt — sonst würde {"$exists": true} weiter greifen.

Keine Parameter.

Anfragekörper `UndoRequest`

Name	Typ	Bedeutung
`entry_id`	string optional	Entry Id
`batch_id`	string optional	Batch Id

Beispiel

curl -X POST "$API/taxonomy/review/undo" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

POST /taxonomy/review/{keyword_id}

Review Decision

Entscheidung für ein Keyword. approve = Zuordnung bestätigen, reject = als falsch markieren, reassign = auf einen anderen Parent umhängen.

Name	Typ	Bedeutung
`keyword_id`	string, im Pfad Pflicht	—

Anfragekörper `ReviewDecision`

Name	Typ	Bedeutung
`verdict`	string Pflicht	Verdict
`parent_id`	string optional	Parent Id
`reviewer`	string optional	Reviewer
`note`	string optional	Note

Beispiel

curl -X POST "$API/taxonomy/review/12345" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

GET /taxonomy/stats

Taxonomy Stats

Übersicht: Anzahl Ebenen und Coverage.

Die Zahlen stammen aus dem Offline-Lauf (keyword_taxonomy/run_all.py) und enthalten die Keywords von Ticker-Kollisionen mit. Rund 3,3 % der keyword_ids (3.744 von 113.842) existieren ausschliesslich, weil sie aus einer Kollisionszeile extrahiert wurden — sie beschreiben eine andere Firma als der Ticker. Ebenso count_sum in kw_taxonomy_parents und n_keywords in kw_taxonomy_grandparents. Bereinigt werden diese Zaehler erst beim naechsten Pipeline-Lauf, wenn step00_export die Zeilen mit enrichment_suspect ueberspringt.

Keine Parameter.

Beispiel

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

GET /taxonomy/stock/{stock_id}

Stock Tags

Parent-/Grandparent-Tags einer Aktie (dedupliziert).

Name	Typ	Bedeutung
`stock_id`	string, im Pfad Pflicht	—
`compare_only`	boolean, in der Abfrage optional · Vorgabe `False`	Nur vergleichsrelevante Arten

Beispiel

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

{
  "isin": "DE0007164600",
  "grandparents": ["Unternehmenssoftware", "Cloud-Infrastruktur"],
  "parents": ["ERP", "Datenbanken", "Business Intelligence"],
  "keywords": 47
}

Thematische Taxonomie

Stocks By Parent

Beispiel

List Grandparents

Beispiel

Grandparent Bulk

Anfragekörper GrandparentBulk

Beispiel

Move Parents

Anfragekörper MoveParents

Beispiel

Grandparent Detail

Beispiel

Patch Grandparent

Anfragekörper GrandparentPatch

Beispiel

Keyword Mapping

Beispiel

Resolve Keywords

Beispiel

List Parents

Beispiel

Parent Keywords

Beispiel

Review Bulk

Anfragekörper BulkReview

Beispiel

Review Log

Beispiel

Review Progress

Beispiel

Review Queue

Beispiel

Review Undo

Anfragekörper UndoRequest

Beispiel

Review Decision

Anfragekörper ReviewDecision

Beispiel

Taxonomy Stats

Beispiel

Stock Tags

Beispiel

Anfragekörper `GrandparentBulk`

Anfragekörper `MoveParents`

Anfragekörper `GrandparentPatch`

Anfragekörper `BulkReview`

Anfragekörper `UndoRequest`

Anfragekörper `ReviewDecision`