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
- }
- {
- ]
- 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 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
- }
- {
- ]
- }
- {
- ]
- topEntities: [
- }
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"
- }
- {
- ]
- nerEntities: [
- }
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"
- }
- {
- ]
- tags: [
- }
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
- }
- {
- }
- {
- ]
- dates: [
- }
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"
- }
- {
- ]
- categories: [
- }
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",
- measures: [
- "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,
- ]