Documentation → Thematic taxonomy

Documentation

Thematic taxonomy

Three levels: keyword, theme, top-level category.

What it is good for is on the product page: Thematic taxonomy

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

Peer comparison: every stock under one parent or grandparent.

Name	Type	Meaning
`parent_id`	string, in path required	—
`level`	string, in query optional · default `parent`	—
`group`	string, in query optional · default `listing`	listing = rohe Tag-Zeilen (Default, unveraendert); company = Trefferliste wie /tickers/by-keyword
`active`	boolean, in query optional	nur aktive/inaktive Titel (nur bei group=company)
`sort`	string, in query optional · default `relevance`	relevance = staerkste Themenzuordnung zuerst; market_cap = groesste Marktkapitalisierung zuerst
`limit`	integer, in query optional · default `200`	—
`offset`	integer, in query optional · default `0`	—

Example

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

GET /taxonomy/grandparents

List Grandparents

The coarse level (~300 categories). Labels come from the curated registry (kw_taxonomy_grandparents) where present; otherwise from a fallback aggregation.

Name	Type	Meaning
`tag_type`	string, in query optional	—
`status`	string, in query optional	draft\|approved\|frozen
`limit`	integer, in query optional · default `500`	—

Example

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.

No parameters.

Request body `GrandparentBulk`

Name	Type	Meaning
`action`	string required	Action
`tag_type`	string optional	Tag Type
`reviewer`	string optional	Reviewer
`dry_run`	boolean optional · default `True`	Dry Run

Example

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.

No parameters.

Request body `MoveParents`

Name	Type	Meaning
`parent_ids`	array required	Parent Ids
`target_grandparent_id`	string required	Target Grandparent Id
`reviewer`	string optional	Reviewer
`dry_run`	boolean optional · default `True`	Dry Run

Example

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

One grandparent with its fine-grained parents (from the registry).

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

Example

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	Type	Meaning
`grandparent_id`	string, in path required	—

Request body `GrandparentPatch`

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

Example

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

The reverse of /parents/{parent_id}/keywords: from ONE keyword upwards to its parent and grandparent.

keyword_id is the same id as in /tickers/keywords and in keywords_multilingual.keyword_id — every keyword has exactly one mapping. Mind status: needs_review means machine-clustered and unconfirmed; candidates shows the alternatives with their score.

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

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

Example

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

GET /taxonomy/keywords/resolve

Resolve Keywords

The batch variant: resolve many keywords to their parents in ONE call — so a client does not have to query a stock's keyword list keyword by keyword. Unmapped ids are absent from the response (no 404).

Name	Type	Meaning
`ids`	string, in query required	Komma-getrennte keyword_ids, max. 500

Example

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

GET /taxonomy/parents

List Parents

The fine-grained level (~7,000 parents).

Name	Type	Meaning
`tag_type`	string, in query optional	—
`grandparent_id`	string, in query optional	—
`search`	string, in query optional	Filtert label_en/label_de
`limit`	integer, in query optional · default `200`	—

Example

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

GET /taxonomy/parents/{parent_id}/keywords

Parent Keywords

Every detail keyword mapped to this parent.

Name	Type	Meaning
`parent_id`	string, in path required	—
`limit`	integer, in query optional · default `500`	—

Example

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.

No parameters.

Request body `BulkReview`

Name	Type	Meaning
`verdict`	string optional · default `approve`	Verdict
`tag_type`	string optional	Tag Type
`ranks`	string optional	Ranks
`min_count`	integer optional · default `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 · default `0.0`	Min Llm Confidence
`keyword_ids`	array optional	Keyword Ids
`reviewer`	string optional	Reviewer
`limit`	integer optional · default `5000`	Limit
`dry_run`	boolean optional · default `True`	Dry Run

Example

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	Type	Meaning
`scope`	string, in query optional	—
`batch_id`	string, in query optional	—
`limit`	integer, in query optional · default `50`	—

Example

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.

No parameters.

Example

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

GET /taxonomy/review/queue

Review Queue

Keywords with status=needs_review — prioritised for review. Highest score first (the most obvious corrections).

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

Example

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.

No parameters.

Request body `UndoRequest`

Name	Type	Meaning
`entry_id`	string optional	Entry Id
`batch_id`	string optional	Batch Id

Example

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

Records a review decision for a keyword. approve = confirm the mapping; reject = mark it wrong; reassign = move it manually to a parent_id (which must exist).

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

Request body `ReviewDecision`

Name	Type	Meaning
`verdict`	string required	Verdict
`parent_id`	string optional	Parent Id
`reviewer`	string optional	Reviewer
`note`	string optional	Note

Example

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

GET /taxonomy/stats

Taxonomy Stats

Overview: number of levels and coverage.

No parameters.

Example

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

GET /taxonomy/stock/{stock_id}

Stock Tags

Parent and grandparent tags of a stock (deduplicated).

Name	Type	Meaning
`stock_id`	string, in path required	—
`compare_only`	boolean, in query optional · default `False`	Nur vergleichsrelevante Arten

Example

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

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

Thematic taxonomy

Stocks By Parent

Example

List Grandparents

Example

Grandparent Bulk

Request body GrandparentBulk

Example

Move Parents

Request body MoveParents

Example

Grandparent Detail

Example

Patch Grandparent

Request body GrandparentPatch

Example

Keyword Mapping

Example

Resolve Keywords

Example

List Parents

Example

Parent Keywords

Example

Review Bulk

Request body BulkReview

Example

Review Log

Example

Review Progress

Example

Review Queue

Example

Review Undo

Request body UndoRequest

Example

Review Decision

Request body ReviewDecision

Example

Taxonomy Stats

Example

Stock Tags

Example

Request body `GrandparentBulk`

Request body `MoveParents`

Request body `GrandparentPatch`

Request body `BulkReview`

Request body `UndoRequest`

Request body `ReviewDecision`