Webservice/API-Zugriff

Allgemeines

Viele Daten dieser Website können direkt über eine HTTP-Schnittstelle abgefragt werden. Bisher wird die Suche nach Wörtern, Teilwörtern und nach ähnlich geschriebenen Wörtern unterstützt. Nicht unterstützt wird die Wikipedia/Wiktionary-Suche.

Hinweis: Die Nutzung der API ist kostenlos, aber es gelten folgende Bedingungen:

1. Wir erwarten einen Link auf www.openthesaurus.de (ohne nofollow-Attribut). Sollten die Daten nur im Hintergrund benutzt werden (z.B. zur Erweiterung einer Suchanfrage o.ä.) reicht auch ein Hinweis im Impressum. Ansonsten sollte der Link für die Nutzer gut sichtbar auf der Seite angezeigt werden, auf der auch die Daten zum Einsatz kommen.
2. Jede Anfrage muss im User-Agent-Header eine Kontaktmöglichkeit (z. B. Homepage oder E-Mail) enthalten, damit wir bei Problemen wissen, mit wem wir Kontakt aufnehmen können.
3. Anfrage-Limitierung: Bei mehr als 60 Anfragen pro Minute von der gleichen IP-Adresse folgt eine Fehlermeldung. Zusätzlich zur direkten Abfrage stehen weiterhin Downloads der Datenbank zur Verfügung. Statt Massenabfragen über die API sollte dieser Download genutzt werden.
4. Wer plant, die API dauerhaft zu benutzen, sollte sich bitte vorher bei feedback at openthesaurus.de melden. Nur so können wir rechtzeitig alle Nutzer kontaktieren, um zum Beispiel über mögliche Änderungen am Ausgabeformat zu informieren.

Suchanfrage für JSON

Mit der folgenden HTTP-Anfrage via GET können alle Synonymgruppen, die das Wort test beinhalten, abgefragt werden:

Kommt im Suchwort ein Sonderzeichen vor, muss es mit UTF-8 URL-kodiert werden (z.B. wird hören zu h%C3%B6ren).

Suchanfrage für XML

Statt application/json kann text/xml angegeben werden, um das Ergebnis im XML-Format zu erhalten.

Optionen

• similar=true: Hiermit werden bei jeder Antwort auch bis zu fünf ähnlich geschriebene Wörter zurückgegeben. Dies ist nützlich, um dem User einen Vorschlag im Falle eines möglichen Tippfehlers machen zu können. Beispielanfrage:
  https://www.openthesaurus.de/­synonyme/search?q=Umstant&­format=application/json&­similar=true
  In der Antwort gibt distance den Levenshtein-Abstand zum Suchwort an (Wörter in Klammern werden dabei ignoriert). Die Wörter sind bereits nach diesem Abstand sortiert. Es werden nur Wörter vorgeschlagen, die auch in OpenThesaurus vorhanden sind.
• substring=true: Hiermit werden bei jeder Antwort auch bis zu zehn Wörter zurückgegeben, die den Suchbegriff nur als Teilwort beinhalten. Beispielanfrage:
  https://www.openthesaurus.de/­synonyme/search?q=Hand&­format=application/json&­substring=true
• substringFromResults: Gibt an, ab welchem Eintrag die Teilwort-Treffer zurückgegeben werden sollen. Funktioniert nur zusammen mit substring=true. Standardwert ist 0, also ab der ersten Position.
• substringMaxResults: Gibt an, wie viele Teilwort-Treffer insgesamt zurückgegeben werden sollen. Funktioniert nur zusammen mit substring=true. Der Standardwert ist 10, Maximalwert ist 250.
• startswith=true: Wie substring=true, findet aber nur Wörter, die mit dem angebenen Suchbegriff anfangen. Beschränkung der Treffer ähnlich wie bei substring, aber mit startsWithFromResults und startsWithMaxResults.
• supersynsets=true: Gibt an, dass zu jeder Synonymgruppe ihre (optionalen) Oberbegriffe mitgeliefert werden.
• subsynsets=true: Gibt an, dass zu jeder Synonymgruppe ihre (optionalen) Unterbegriffe mitgeliefert werden.
• baseform=true: Gibt die Grundform zum Suchwort an, falls es sich nicht schon um eine Grundform handelt. Beispiel: "Krankenhäuser" liefert "Krankenhaus" (nur JSON).

Bekannte Probleme

Umlaute werden bei der Suche wie ihre nicht-Umlaute behandelt, so findet tur auch den Eintrag zu Tür und umgekehrt.