API-Dokumentation - Response

Die Antwort ist immer im JSON-Format und enthält neben dem analysierten Text und der Sprache des Textes pro angefragtem Service einen Antwortblock mit dem Analyse-Ergebnis für den betreffenden Service. Die Struktur der jeweiligen Service-Antworten wird detailliert weiter unten beschrieben.

Ein Beispiel für eine vollständige Antwort finden Sie im Abschnitt Überblick.

Grundlegendes Antwortformat

{
- 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.",
- timestamp: 1400247994051,
- language: "de",
- entities: [
- ]
- lexiconEntities:
- [
- ]
- nerEntities:
- [
- ]
- lexiconTags:
- [
- ]
- tags:
- [
- ]
- dates:
- [
- ]
- categories:
- [
- ]
- measures:
- [
- ]
- fingerprints:
- [
- ]
- legals:
- [
- ]
}

Hat ein Service den Text erfolgreich analysiert, aber keine Ergebnisse gefunden, so ist in der Antwort der Service-Block mit einer leeren Ergebnisliste enthalten. Tritt bei der Anfrage an einen einzelnen Service ein Fehler auf, dann antwortet die Neofonie-Textmining-API mit dem HTTP-Status 200 und dem üblichen Antwortformat, in dem dann allerdings dieser eine Service nicht enthalten ist. Nicht angefragte Services sind generell nicht in der Antwort enthalten.

Beschreibung der einzelnen Felder:

text	Der analysierte Text. Falls eine URL angegeben wurde, ist hier der von der Webseite extrahierte Text enthalten, der die Grundlage der Analyse war. Wurde der Text direkt über den Text-Parameter angegeben, ist er unverändert hier wieder enthalten. Wurde der Text über ein JSON-Dokument übergeben, werden die einzelnen Textabschnitte zu einem Textblock konkateniert zurückgegeben.
language	Die für den Text erkannte Sprache, z.B. "de", "en" oder "ru".
timestamp	Der Zeitstempel der Antwort (in Millisekunden seit 1. Januar 1970).

Antwortformat: Entities

{
- entities: [
  - {
    - confidence: 36.218177795410156,
    - relevance: 25.53207015991211,
    - surface: "GmbH",
    - label: "Gesellschaft mit beschränkter Haftung",
    - uri: "https://www.wikidata.org/wiki/Q460178",
    - type: "CONCEPT",
    - start: 44,
    - end: 48
  - },
  - {
    - confidence: 39.26929473876953,
    - relevance: 11.950702667236328,
    - surface: "Berlin",
    - label: "Berlin",
    - uri: "https://www.wikidata.org/wiki/Q64",
    - type: "PLACE",
    - start: 57,
    - end: 63
  - },
  - {
    - confidence: 95.73828125,
    - relevance: 35.542537689208984,
    - surface: "Texten",
    - label: "Text",
    - uri: "https://www.wikidata.org/wiki/Q234460",
    - type: "CONCEPT",
    - start: 150,
    - end: 156
  - }
- ]
}

Beschreibung der einzelnen Felder:

label	Das eindeutige Label der Entität.
surface	Die Oberflächenform der Entität im Text.
type	Der Typ der Entität. Mögliche Werte sind "PERSON", "PLACE", "ORGANISATION", "JOBTITLE", "WORK", "EVENT" und "CONCEPT". Dieser wird heuristisch ermittelt und kann in Einzelfällen vom erwarteten Wert abweichen. Beispiel: Eine Stadt kann als Arbeitgeber fungieren und wird ggf. daher als Organisation eingestuft.
uri	Die Wikidata-URI der Entität. Kann nicht gesetzt sein, falls der Typ der Entität zwar erkannt wird, aber die Entität nicht bekannt ist.
confidence	Konfidenzwert, repräsentiert die Sicherheit bei der Entitätserkennung. Ein höherer Wert steht für eine sicherere Erkennung. Der Konfidenzwert hat keine obere Grenze.
relevance	Relevanzwert, repräsentiert die Relevanz der Entität für den Text. Ein höherer Wert steht für eine wichtigere Entität. Der Relevanzwert hat keine obere Grenze.
start	Die Startposition der Entität im Text.
end	Die Endposition der Entität im Text.

Folgende Felder können in der Antwort enthalten sein, je nachdem, welche der optionalen Parameter im Request enthalten sind::

annotations	Zusätzliche Annotationsinformationen zu den Entitäten. Nur wenn beim Request der zusätzliche Parameter ner Annotations enthalten ist.
annotations.aliases	Andere Bezeichnungen für die Entität. Das Feld ist nicht im Antwortblock enthalten, wenn keine anderen Bezeichnungen auf Wikidata hinterlegt sind.
annotations.wikipedia	Link zu einer Wikipedia-Seite zur Entität. Feld ist nicht im Antwortblock enthalten, wenn für die Entität keine Wikipedia-Seite auf Wikidata verlinkt ist.
candidates	Alle möglichen Disambiguierungskandidaten für die betreffende Entität. Nur wenn beim Request der Parameter nerFormat den Wert 'candidates' erhalten hat.
candidates.uri	Die Wikidata-URI des Disambiguierungskandidaten.
candidates.type	Der Typ des Disambiguierungskandidaten. Mögliche Werte sind "PERSON", "PLACE", "ORGANISATION", "JOBTITLE", "WORK", "EVENT" und "CONCEPT". Dieser wird heuristisch ermittelt und kann in Einzelfällen vom erwarteten Wert abweichen. Beispiel: Eine Stadt kann als Arbeitgeber fungieren und wird ggf. daher als Organisation eingestuft.
candidates.confidence	Konfidenzwert für den Disambiguierungskandidaten. Repräsentiert die Sicherheit bei der Entitätserkennung. Ein höherer Wert steht für eine sicherere Erkennung. Der Konfidenzwert hat keine obere Grenze.
candidates.label	Das eindeutige Label des Disambiguierungskandidaten.
userDefinedFields	Zusätzliche Informationen zu den Entitäten, abhängig vom User. Nur wenn beim Request die beiden zusätzlichen Parameter nerMetadata und nerMetadataProperties genutzt werden. Die Rückgabe erfolgt im Key-Value-Format, dessen konkrete Benennung abhängig davon ist, welche zusätzlichen Felder durch den User definiert wurden.

Antwortformat: Top Entities

Top-Entitäten werden in der Response gelistet, wenn der Parameter nerFormat beim Request auf den Wert 'aggregate' gesetzt wurde. Die Top-Entitäten umfassen dann diejenigen Entitäten im Text, die die höchsten Relevanzwerte aufweisen.

{
- topEntities: [
  - {
    - confidence: 95.73828125,
    - relevance: 35.542537689208984,
    - label: "Text",
    - uri: "https://www.wikidata.org/wiki/Q234460",
    - type: "CONCEPT",
    - matches: [
      - {
        
        surface: "Texten",
        
        start: 150,
        
        end: 156
      - }
    - ]
  - },
  - {
    - confidence: 100.0,
    - relevance: 33.77956008911133,
    - label: "Neofonie GmbH",
    - uri: "Neofonie",
    - type: "Organisation",
    - userDefinedFields:
      - {
      - }
    - matches: [
      - {
        
        surface: "Neofonie GmbH",
        
        start: 35,
        
        end: 48
      - }
    - ]
  - },
  - {
    - confidence: 36.218177795410156,
    - relevance: 25.53207015991211,
    - label: "Gesellschaft mit beschränkter Haftung",
    - uri: "https://www.wikidata.org/wiki/Q460178",
    - type: "CONCEPT",
    - matches: [
      - {
        
        surface: "GmbH",
        
        start: 44,
        
        end: 48
      - }
    - ]
  - },
  - {
    - confidence: 39.26929473876953,
    - relevance: 11.950702667236328,
    - label: "Berlin",
    - uri: "https://www.wikidata.org/wiki/Q64",
    - type: "PLACE",
    - matches: [
      - {
        
        surface: "Berlin",
        
        start: 57,
        
        end: 63
      - }
    - ]
  - }
- ]
}

Beschreibung der einzelnen Felder:

label	Das eindeutige Label der Entität.
type	Der Typ der Entität. Mögliche Werte sind "PERSON", "PLACE", "ORGANISATION", "JOBTITLE", "WORK", "EVENT" und "CONCEPT". Dieser wird heuristisch ermittelt und kann in Einzelfällen vom erwarteten Wert abweichen. Beispiel: Eine Stadt kann als Arbeitgeber fungieren und wird daher ggf. als Organisation eingestuft.
uri	Die Wikidata-URI der Entität. Kann nicht gesetzt sein, falls der Typ der Entität zwar erkannt wird, aber die Entität nicht bekannt ist.
confidence	Konfidenzwert, repräsentiert die Sicherheit bei der Entitätserkennung. Ein höherer Wert steht für eine sicherere Erkennung. Der Konfidenzwert hat keine obere Grenze.
relevance	Relevanzwert, repräsentiert die Relevanz der Entität für den Text. Ein höherer Wert steht für eine wichtigere Entität. Der Relevanzwert hat keine obere Grenze.
matches	Die Fundstellen der Entität im Text.
matches.surface	Die Oberflächenform der Fundstelle im Text.
matches.start	Die Startposition der Fundstelle im Text.
matches.end	Die Endposition der Fundstelle im Text.

Antwortformat: Lexicon Entities

Basis für diese Entitäten ist ein in TXTWerk gepflegtes Lexicon. Im Gegensatz zu den auf Wikidata-Basis ermittelten Entitäten findet hier keine Disambiguierung statt. Das Rückgabeformat ist bis auf den Namen des Antwortblocks 'lexiconEntities' identisch zu 'entities'.

Beschreibung der einzelnen Felder:

label	Das eindeutige Label der Entität.
surface	Die Oberflächenform der Entität im Text.
type	Der Typ der Entität. Mögliche Werte werden im Lexikon gepflegt und hängen von dessen Bearbeitungsstand ab.
uri	Eine dieser Entität zugeordnete URI, typischerweise eine ID in einem externen System.
relevance	Relevanzwert, repräsentiert die Relevanz der Entität für den Text. Ein höherer Wert steht für eine wichtigere Entität. Der Relevanzwert hat keine obere Grenze.
confidence	Konfidenzwert, der für diesen Service aufgrund der Lexikon-Basis allerdings immer 1 beträgt.
start	Die Startposition der Entität im Text.
end	Die Endposition der Entität im Text.
userDefinedFields	Zusätzliche Informationen zu den Entitäten, abhängig vom User.

Antwortformat: NER Entities

{
- nerEntities: [
  - {
    - type: "ORGANISATION",
    - confidence: 0.6897694170475006,
    - start: 35,
    - end: 48,
    - surface: "Neofonie GmbH"
  - },
  - {
    - type: "PLACE",
    - confidence: 0.9957075119018555,
    - start: 57,
    - end: 63,
    - surface: "Berlin"
  - }
- ]
}

Beschreibung der einzelnen Felder:

surface	Die Oberflächenform der Entität im Text.
type	Der Typ der Entität. Mögliche Werte sind "PERSON" und "PLACE".
confidence	Konfidenzwert, repräsentiert die Sicherheit bei der Entitätserkennung. Ein höherer Wert steht für eine sicherere Erkennung. Der Konfidenzwert hat keine obere Grenze.
start	Die Startposition der Entität im Text.
end	Die Endposition der Entität im Text.

Antwortformat: Tags

{
- tags: [
  - {
    - confidence: 0.9989658313414402,
    - term: "TXTWerk"
  - },
  - {
    - confidence: 0.9782419755349671,
    - term: "Entitäten"
  - },
  - {
    - confidence: 0.9732933133596776,
    - term: "Textmining-API"
  - },
  - {
    - confidence: 0.9365462323616698,
    - term: "Neofonie GmbH"
  - },
  - {
    - confidence: 0.8993179739843555,
    - term: "Schlagwörter"
  - },
  - {
    - confidence: 0.8814831569459867,
    - term: "Berlin"
  - },
  - {
    - confidence: 0.874798029178814,
    - term: "Fullservice-Provider"
  - }
- ]
}

Beschreibung der einzelnen Felder:

term	Das gefundene Schlagwort.
confidence	Konfidenzwert des Schlagworts, immer zwischen 0 und 1.

Antwortformat: Lexicon Tags

{
- 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.",
- lexiconTags: [
  - {
    - id: "[unique id]",
    - tag: "ansässig",
    - score: 7.6243725,
    - analyzed: "ansässig",
    - observedSurfaces: [
      - {
        
        start: 64,
        
        end: 74,
        
        type: "TAG",
        
        observedSurface: "ansässiger",
        
        analyzed: "ansässig"
      - }
    - ]
  - }
- ]
}

Beschreibung der einzelnen Felder:

id	Die eindeutige ID des Schlagworts im User-Lexikon.
tag	Das eindeutige Label des Schlagworts.
score	Score über die Qualität der Übereinstimmung zwischen den Fundstellen im Text und dem Schlagwort im User-Lexikon. Wird durch den Matching-Algorithmus erzeugt.
analyzed	Schlagwörter werden durch den Algorithmus in verschiedene Wortformen überführt. Hier wird diejenige Form des Schlagworts aufgeführt, die gematcht hat.
observedSurfaces	Die Fundstellen des Schlagworts im Text.
observedSurfaces.start	Die Startposition der Fundstelle im Text.
observedSurfaces.end	Die Endposition der Fundstelle im Text.
observedSurfaces.type	Die Art des Matches. Mögliche Werte sind "TAG", "SYNONYM" und "GENDER".
observedSurfaces.observedSurface	Die Oberflächenform der Fundstelle im Text.
observedSurfaces.analyzed	Die einzelnen Token im Text werden durch den Algorithmus in verschiedene Wortformen überführt. Hier wird diejenige Form des Tokens aufgeführt, die gematcht hat.

Antwortformat: Dates

{
- dates: [
  - {
    - surface: "08.09.2023",
    - start: 196,
    - end: 206,
    - dateStart:
      - {
        
        day: 8,
        
        month: 9,
        
        year: 2023,
        
        bc: false
      - }
    - dateEnd:
      - {
        
        day: 8,
        
        month: 9,
        
        year: 2023,
        
        bc: false
      - }
  - }
- ]
}

Beschreibung der einzelnen Felder:

surface	Die Oberflächenform des Datums im Text.
start	Die Startposition des Datums im Text.
end	Die Endposition des Datums im Text.
dateStart	Das Startdatum. Ein Datum wird immer als Zeitraum repräsentiert, mit eventuell zusammenfallendem Start- und Enddatum.
dateEnd	Das Enddatum.
day	Der Tag des Start- bzw. Enddatums. Mögliche Werte sind 1-31.
month	Der Monat des Start- bzw. Enddatums. Mögliche Werte sind 1-12.
year	Das Jahr des Start- bzw. Enddatums.
bc	Beschreibt, ob das Datum sich auf die Zeit vor Christus bezieht. Mögliche Werte sind true und false.

Antwortformat: Categories

{
- categories: [
  - {
    - confidence: 0.9999914614615732,
    - label: "internet"
  - },
  - {
    - confidence: 8.5340630740002E-6,
    - label: "kultur"
  - },
  - {
    - confidence: 3.4390082461387908E-9,
    - label: "auto+technik"
  - },
  - {
    - confidence: 7.942384268635301E-10,
    - label: "wirtschaft"
  - },
  - {
    - confidence: 1.1799574174439144E-10,
    - label: "reisen"
  - },
  - {
    - confidence: 8.06441429999464E-11,
    - label: "wissenschaft"
  - },
  - {
    - confidence: 4.031349737157026E-11,
    - label: "politik"
  - },
  - {
    - confidence: 3.152736753221788E-12,
    - label: "sport"
  - }
- ]
}

Beschreibung der einzelnen Felder:

label	Der Name der Kategorie. Mögliche Werte sind "Politik", "Wirtschaft", "Auto & Technik", "Internet", "Kultur", "Reisen", "Sport", "Vermischtes" und "Wissenschaft"
confidence	Der Konfidenzwert für die Kategorie, immer zwischen 0 und 1.

Antwortformat: Measures

{
- measures: [
  - {
    - start: 228,
    - end: 231,
    - text: "24h",
    - valueString: "24",
    - unitString: "h",
    - type: "TIME",
    - alias: [
    - "24 h",
    - "24h",
    - "24Stunde",
    - "24 Stunde",
    - "24 Stunden",
    - "24Stunden",
    - ]
  - }
- ]
}

Beschreibung der einzelnen Felder:

start	Die Startposition der Maßzahl im Text.
end	Die Endposition der Maßzahl im Text.
text	Die Zeichenkette, so wie sie im Text vorkommt.
valueString	Der Wert der Maßzahl als Zeichenkette, so wie sie im Text vorkommt.
unitString	Die Einheit der Maßzahl als Zeichenkette, so wie sie im Text vorkommt.
unitCanonical	Nur bei Währungen. Unabhängig vom konkreten String der Einheit im Text handelt es sich hier um den Drei-Buchstaben-Code der jeweiligen Währung.
type	Der Typ der Maßzahl. Mögliche Werte sind "LENGTH", "AREA", "MASS", "TEMPERATURE", "VOLTAGE", "AMPERAGE", "RESISTANCE", "CHARGE", "CAPACITY", "CONDUCTANCE", "INDUCTANCE", "MAGNETIC_STRENGTH", "POWER", "ENERGY", "FORCE", "PRESSURE", "FREQUENCY", "VOLUME", "LUMINOSITY", "ILLUMINANCE", "SPIN", "SUBSTANCE", "RADIOACTIVITY", "CURRENCY", "TIME", "UNKNOWN"
alias	Andere Schreibweisen der Zeichenkette (mit und ohne Spatium, Einheiten abgekürzt oder ausgeschrieben, Umrechnungen). Nicht vorhanden beim Typ "CURRENCY".

Antwortformat: Fingerprints

{
- fingerprints: [
- 7493129,
- 18632078,
- 48467713,
- 64740551,
- 61803666,
- 57602,
- 20683602,
- 7169662,
- 124073776,
- 1324512,
- 48689911,
- 63618400,
- 82739683,
- 57114900,
- 86498997,
- 5531749,
- 43615458,
- 63266708,
- 35312651,
- 1767346,
- 166345084,
- 20994017,
- 10618634,
- 35187378,
- 52012568,
- 62221932,
- 101283997,
- 194238108,
- 24943142,
- 48857582,
- 214343186,
- 8807040,
- 11737208,
- 29004557,
- 33563369,
- 23510317,
- 54409541,
- 58494605,
- 55886581,
- 88208507,
- 10609552,
- 7042020,
- 21855281,
- 9560326,
- 22894461,
- 19569052,
- 11695122,
- 59192088,
- 11647472,
- 25992587,
- ]
}