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 die URL einer zu analysierenden Webseite angegeben werden. In diesem Fall wird die Webseite gecrawlt und ihr wesentlicher Textinhalt bestimmt und verarbeitet. Fremde Elemente wie die Navigation oder Teaser-Texte werden aussortiert.
Eine Gewichtung von Eingabetexten erfolgt, indem ein Dokument als JSON-String übergeben wird. Die Relevanz-Werte der Ergebnisse werden mit der eingegeben Gewichtung multipliziert. Die 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 Kategorien (Standardmäßig sind das: "Politik", "Wirtschaft", "Auto & Technik", "Internet", "Kultur", "Sport", "Reisen", "Vermischtes" und "Wissenschaft"). |
| dates | Datumsangaben und Zeiträume. |
| measures | Maßzahlen und -einheiten, die im Text enthalten sind. |
| authors | Autoren eines als HTML-Dokument vorliegenden Artikels. |
| fingerprints | Fingerprints für den Text als Grundlage zur Erkennung von ähnlichen Dokumenten. |
| lexiconEntities | Named Entities auf Basis eines User-Lexikons, das zusätzlich zu den Daten aus Wikidata in TXTWerk gepflegt werden kann. |
| lexiconTags | Schlagwörter auf Basis eines in TXTWerk gepflegten Lexikons. |
| nerEntities | Named Entities, die nicht aus der Wikidata-Ontologie oder dem User-Lexikon stammen, sondern durch ein destilliertes Flair-Modell erkannt werden. |
Servicesteuerung
Für einzelne Services stehen weitere Parameter zur Verfügung, mit denen die Analyse oder das Ergebnis beeinflusst werden können.
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-String.
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, Default: 30 Werte: nichtnegative ganze Zahl |
| nerMinRelevance | Servicesteuerung |
Schwellwert für den Relevanzwert 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' (gelistete Disambiguierungskandidaten für jede Entität) |
| nerMetadata | Servicesteuerung |
Zusätzliche Metadaten für die Entitäten.
Service: entities. Erforderlich: nein Werte: true oder false |
| nerMetadataProperties | Servicesteuerung |
Eigenschaften, die für die gefundenen Entitäten zurückgegeben werden sollen.
Service: entities. Erforderlich: nein Werte: Komma-separierte Liste. Abhängig davon, welche Properties im Key-Value-Format durch den User vorher angelegt wurden, z.B. 'description' (falls Entitäten eine Beschreibung beigefügt wurde) oder 'typetree' (falls Informationen über hierarchische Beziehungen zwischen Entitäten hinterlegt wurden). null übergibt alle vorhandenen Properties. |
| nerAnnotations | Servicesteuerung |
Zusätzliche Informationen zu den Entitäten wie z.B. Wikipedia-Seiten und Aliases.
Service: entities. Erforderlich: nein Werte: Komma-separierte Liste, die eine oder mehrere der verfügbaren Annotationsebenen enthält (derzeit 'aliases' und 'wikipedia'). |
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='TXTWerk ist die Textmining-API der Neofonie GmbH, ein in Berlin ansässiger Fullservice-Provider. Neben Entitäten und Schlagwörtern erkennt TXTWerk in Texten unter anderem auch Datumsangaben (z.B. 08.09.2023) und Maßzahlen (z.B. 24h) und ordnet jeden Text einer passenden Textklasse zu.' \
-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 gewichtetes 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" }]'