---

Webservice/API-Zugriff

• Allgemeines
• Suchanfrage für XML
• Suchanfrage für JSON
• Suchanfrage für JSONP
• Optionen
• Bekannte Probleme
• Anfrage-Limitierung

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. Noch nicht unterstützt wird die Wikipedia/Wiktionary-Suche.

Hinweis: wer die API über reines Testen hinaus benutzt, 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 XML

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

http://www.openthesaurus.de/synonyme/search?q=test&format=text/xml

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

Ergebnis

Das Ergebnis der Anfrage ist eine XML-Datei mit folgendem Format:

<matches>
  <metaData>
    <apiVersion content="0.1.3"/>
    <warning content="WARNING -- this XML format may be extended without warning"/>
    <copyright content="Copyright (C) 2011 Daniel Naber (www.danielnaber.de)"/>
    <license content="GNU LESSER GENERAL PUBLIC LICENSE Version 2.1"/>
    <source content="http://www.openthesaurus.de"/>
    <date content="Sat Mar 06 22:47:25 CET 2011"/>
  </metaData>
  <synset id="1234">
    <categories>
      <category name="Name der Kategorie"/>
    </categories>
    <term term="Bedeutung 1, Wort 1"/>
    <term term="Bedeutung 1, Wort 2"/>
  </synset>
  <synset id="2345">
    <categories/>
    <term term="Bedeutung 2, Wort 1"/>
  </synset>
</matches>

Suchanfrage für JSON

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

http://www.openthesaurus.de/synonyme/search?q=test&format=application/json

Hinweis: die JSON-API kann sich noch ändern. Wer sie außer zu Testzwecken nutzen möchte, sollte vorher mit feedback@openthesaurus.de Kontakt aufnehmen.

Suchanfrage für JSONP

Mit der Übergabe einer Callback-Methode kann der JSON-Code als Parameter einer Funktion übergeben werden. Eine Beispiel-Seite.

http://www.openthesaurus.de/synonyme/
search?q=test&format=application/json&callback=myCallback

Hinweis: die JSON-API kann sich noch ändern. Wer sie außer zu Testzwecken nutzen möchte, sollte vorher mit feedback@openthesaurus.de Kontakt aufnehmen.

Optionen

• format=text/xml oder format=application/json: Aktiviert den API-Modus, so dass die Antwort als XML bzw. JSON zurückgeliefert wird.
• callback: siehe JSONP
• 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:

  http://www.openthesaurus.de/synonyme/search?q=Umstant&format=text/xml&similar=true

  Antwort (Ausschnitt):

  <similarterms>
    <term term="Umstand" distance="1"/>
    <term term="(zeitlicher) Abstand" distance="3"/>
    <term term="Abstand" distance="3"/>
    <term term="amüsant" distance="3"/>
    <term term="Anstalt" distance="3"/>
  </similarterms>
  

  distance gibt 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:

  http://www.openthesaurus.de/synonyme/search?q=Hand&format=text/xml&substring=true

  Antwort (Ausschnitt):

  <substringterms>
    <term term="(etwas) behandeln"/>
    <term term="abhandeln"/>
  </substringterms>
  

• 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 (seit August 2012, bisher nur für XML).
• subsynsets=true: Gibt an, dass zu jeder Synonymgruppe ihre (optionalen) Unterbegriffe mitgeliefert werden (seit August 2012, bisher nur für XML).
• mode=all: Aktiviert alle zusätzlichen Abfragen. Bisher sind das similar=true, substring=true, supersynsets=true und subsynsets=true. Dieser Modus sollte nur zum Testen benutzt werden, um einen Überblick über die Möglichkeiten zu bekommen.

Bekannte Probleme

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

Anfrage-Limitierung

Bei mehr als 60 Anfragen pro Minute von der gleichen IP-Adresse folgt eine Fehlermeldung (HTTP-Code 500). Wer mehr Anfragen stellen möchte, kann uns kontaktieren und um eine Erhöhung des Limits bitten. Zusätzlich zur direkten Abfrage stehen weiterhin Downloads der Datenbank zur Verfügung. Statt Massenabfragen über die API sollte dieser Download genutzt werden.