API Dokumentation - Request

Der Request kann als GET oder als POST Request an die URL
https://api.txtwerk.de/rest/txt/analyzer
erfolgen. Das zu annotierende Dokument und die Auswahl der anzuwendenden Services werden als Parameter übergeben.

Dokument

Das zu annotierende Dokument kann direkt als Text übergeben werden.

Alternativ kann auch einfach die URL einer zu analysierenden Webseite angegeben werden. In diesem Fall wird die Webseite gecrawlt, der wesentliche Textinhalt bestimmt und verarbeitet. Fremde Elemente wie die Navigation oder Teaser-Texte werden aussortiert.

Gewichtung von Eingabetexten erfolgt indem man document als JSON-String eingibt. Die Relevanz-Werte der Ergebnisse werden mit der eingegeben Gewichtung multipliziert. Der Antwort ist dann nach den eingegebenen Text-Abschnitten strukturiert.

Services

Das Dokument kann mit verschiedenen Techniken analysiert werden. Zur Auswahl stehen folgende Services

entities	Named Entities auf Basis der Wikidata Ontologie.
tags	Schlagwörter, die im Text vorkommen, den Inhalt gut beschreiben und zusammenfassen.
categories	Zuordnung des Texts zu den Kategorien Politik, Wirtschaft, Auto & Technik, Internet, Kultur, Politik, Reisen, Vermischtes, Wissenschaft.
dates	Datumsangaben und Zeiträume.
measures	Maßzahlen die im Text enthalten sind.
authors	Autoren des als HTML-Dokument vorliegenden Artikels.
fingerprints	Fingerprints für den Text zur Erkennung von ähnlichen Dokumenten.
lexiconEntities	Named Entites auf Basis eines in TXT Werk gepflegten Lexikons.
lexiconTags	Schlagwörter auf Basis eines in TXTWerk gepflegten Lexikons.
nerEntities	Flair/Ner Enititäten

Servicesteuerung

Für einzelne Services stehen weitere Parameter zur Verfügung, mit denen die Analyse oder das Ergebnis beeinflusst werden können.

Beispielanfrage

Beispiel für einen POST Request, bei dem das Dokument direkt als Text übergeben wird:

curl "https://api.txtwerk.de/rest/txt/analyzer" \
    -H "X-Api-Key: ..." \
    -d text='Angela Merkel wurde am 17. Juli 1954 in Hamburg als Angela Dorothea Kasner geboren.' \
    -d services='entities'

Beispiel für einen POST Request, bei dem eine HTML Datei direkt als Parameter übergeben wird:

curl "https://api.txtwerk.de/rest/txt/analyzer" \
    -H "X-Api-Key: ..." \
    -F htmlFile='@' \
    -F services='entities'

Beispiel für einen POST Request, bei dem ein JSON-Dokument übergeben wird:

curl "https://api.txtwerk.de/rest/txt/analyzer" \
    -H "X-Api-Key: ..." \
    -d services='entities'
    -d document='[{ "text": "Titel", "weight": "2.0" } , { "text": "Teaser", "weight": "1.5" }]'

Parameterübersicht

Parameter	Bereich	Beschreibung
text	Dokument	Enthält das zu annotierende Dokument als Text. Für längere Texte empfiehlt sich, die Anfrage als POST Request abzusetzen und den Text im Request Body zu übergeben. Erforderlich: entweder text oder htmlFile oder document Werte: Text
htmlFile	Dokument	Enthält das zu annotierende Dokument als Html-Text. Erforderlich: entweder text oder htmlFile oder document Werte: Html Text Datei
document	Dokument	Enthält das zu annotierende Dokument als JSON. Erforderlich: entweder text oder htmlFile oder document Werte: JSON-String
title	Dokument	Titel des Dokumentes. Durch die zusätzliche Angabe eines Titels kann das Ergebnis verbessert werden. Wird nur für folgende Services berücksichtigt: tags. Erforderlich: nein Werte: Text
teaser	Dokument	Teaser des Dokumentes. Durch die zusätzliche Angabe eines Teasers kann das Ergebnis verbessert werden. Wird nur für folgende Services berücksichtigt: tags. Erforderlich: nein Werte: Text
services	Services	Liste der anzufragenden Services. Erforderlich: ja Werte: komma-separierte Liste, die mindestens einen der unterstützten Services enthält: [entities, tags, categories, dates, measures, authors, fingerprints, lexiconEntities, lexiconTags, nerEntities]
language	Servicesteuerung	Sprache des Eingabetexts. Durch diese Angabe können gezielt sprachabhängige Komponenten aktiviert werden. Erforderlich: nein, wird dann automatisch bestimmt Werte: 'de' oder 'en'
ntags	Servicesteuerung	Anzahl der Schlagwörter, die maximal bestimmt werden sollen. Service: tags. Erforderlich: nein, Default: 10 Werte: nichtnegative ganze Zahl
ncategories	Servicesteuerung	Anzahl der zurückgegebenen Kategorien. Service: categories. Erforderlich: nein Werte: nichtnegative ganze Zahl
nentities	Servicesteuerung	Anzahl der zurückgegebenen Entitäten. Service: entities. Erforderlich: nein Werte: nichtnegative ganze Zahl
nerMinConfidence	Servicesteuerung	Schwellwert für den Konfidenzwert bei den Entitäten. Service: entities. Erforderlich: nein Werte: nichtnegative ganze Zahl
nerMinRelevance	Servicesteuerung	Schwellwert für die Relevanz bei den Entitäten. Service: entities. Erforderlich: nein Werte: nichtnegative ganze Zahl
nerFormat	Servicesteuerung	Ausgabeformat der Entitäten. Service: entities. Erforderlich: nein Werte: 'list', 'aggregate' (aggregierte, nach Relevanz sortierte Liste von Entitäten), 'candidates' (Disambiguierungskandidaten sind gelistet für jede mögliche Entity)