Wenn man SEMPRIA-Search als Software-as-a-Service (Saas) betreiben möchte, kann man die in diesem Abschnitt beschriebene API verwenden. Man benötigt die Information, wo der SaaS erreichbar ist. In diesem Dokument nehmen wir die folgende fiktive Service-URL: https://finde.maschine/ . Jede URL für die API muss mit dieser Service-URL beginnen. Nach dem abschließenden Fragezeichen folgen ein oder mehrere Parameter, deren Bedeutung und Format im Folgenden beschrieben wird. Reale Service-URLs enthalten oft eine Portnummer, z.B. https://finde.maschine:1234/ Alle Service-URLs verwenden das sichere Protokoll HTTPS (statt HTTP), so dass weder die Anfragen noch die Ergebnisseiten von Dritten mitgelesen werden können. (Dies kann nur gewährleistet werden, solange der Computer, von dem aus die API angesprochen wird, nicht kompromittiert ist, also nicht in der Sicherheit durch Sicherheitslücken, Hackerangriffe o.ä. eingeschränkt ist.) Weitergehende Verschlüsselungen können individuell vereinbart werden.
Falls der Zugang Passwort-geschützt vereinbart wurde, müssen an jede URL ein Parameter &pw=IhrPasswort und ein Parameter &corpus=IHRE-CORPUS-ID angehängt werden. Falls ein IP-beschränkter Zugang eingerichtet wurde, so muss die IP des anfragenden Computers in der beim SaaS-Server hinterlegten Whitelist enthalten sein.
2.4.1.1 Suchanfrage (Parameter sentence) Die eigentliche Suchanfrage ist der zentrale Parameter der API und darf nicht fehlen. Beispielsuche nach Oboe, in allen Wortformen und möglichen semantisch verwandten Formulierungen: https://finde.maschine/sempria-search?sentence=Oboe
Die restlichen Parameter sind optional für den Aufruf der Suchmaschine. Je nachdem welche Metadaten Ihre Dokumentenkollektion enthält, ist nur ein Teil der Parameter sinnvoll.
2.4.1.2 Autor (Parameter author) Treffer müssen zusätzlich zur Suchanfrage auch die Bedingung erfüllen, dass der Autor des Textes mit dem des Parameterwerts übereinstimmt. Beispiel: https://finde.maschine/sempria-search?sentence=Oboe&author=Max
2.4.1.3 Zeitliche Einschränkung (Parameter date-begin, Parameter date-end) Die Treffer werden eingeschränkt bezüglich ihres Schreibdatums (date). Dazu kann date-begin, date-end oder beides verwendet werden. Die Datumsangabe muss in der kompakten Variante von ISO 8601 geschehen, also 20251231 für den 31. Dezember 2025. Die angegebenen Werte sind inklusiv zu verstehen, so dass das folgende Beispiel bedeutet, dass Dokumente vom 31. Dezember 2025 oder danach gesucht sind: https://finde.maschine/sempria-search?sentence=Oboe&date-begin=20251231
2.4.1.4 Dokumentenbereiche (Parameter class1, Parameter class2) Falls die Metadaten der Dokumentenkollektion Bereiche, Arten oder Klassen definieren, dann kann man diese Klassifikation unter dem Parameter class1 (weitere Klassifikation bei Bedarf unter class2) einschränken. Falls der Bereich presse definiert ist, kann man so auf diesen Bereich einschränken: https://finde.maschine/sempria-search?sentence=Oboe&class1=presse
2.4.1.5 Titel (Parameter title) Treffer müssen zusätzlich die Bedingung erfüllen, dass die gegebenen Wörter genau so im Titel vorkommen. Beispiel: https://finde.maschine/sempria-search?sentence=Oboe&title=Lexikon+Instrumente
2.4.1.6 Dokumentenformat (Parameter format) Manche Dokumentenkollektionen unterscheiden Dokumententypen wie pdf, docx oder html. In diesem Fall kann mit dem Parameter die Suche auf einen oder mehrere Dokumententypen eingeschränkt werden. Beispiel: https://finde.maschine/sempria-search?sentence=Oboe&format=pdf
2.4.1.7 Adressat (Parameter addree) Das Adressaten-Feld ist meist nur in Dokumentenkollektionen mit Kommunikationscharakter sinnvoll besetzt. Solche Kollektionen können Mailsammlungen, Briefsammlungen o.ä. sein. Im folgenden Beispiel sind nur Treffer mit dem Empfänger Moritz erwünscht: https://finde.maschine/sempria-search?sentence=Oboe&addree=Moritz
2.4.1.8 Stichwortphrasen (Parameter keytopics) Falls ihre Dokumentenkollektion automatisch von SEMPRIA-Search berechnete (oder manuell gepflegte) Stichwortphrasen enthält, so kann der Parameter keytopics verwendet werden. Leerzeichen innerhalb einer Phrase müssen als Unterstrich geschrieben werden. Beispiel: https://finde.maschine/sempria-search?sentence=Oboe&keytopics=San_Remo
2.4.1.9 Restliche Suchparameter Die folgenden Parameter sind nur für einige Dokumentenkollektionen sinnvoll und sind bei Bedarf genauer zu dokumentieren: author-place (Schreibort), addree-place (Empfängerort), category (ähnlich zu class1, class2), coords/coord-radius (Koordinaten und Umkreis), date-y (Datumsangabe nur als ein Jahr oder mehrere Jahre), tags (Name von benutzerdefinierten Kollektionen), url (Teil der Dokumenten-URL).
2.4.1.10 Ausgabeformat (Parameter oformat) Die Ergebnisse einer Suchanfrage mit den oben beschriebenen Parametern werden in einem HTML-Format geliefert. Andere Formate als html kann man über den Parameter oformat anfordern. Es werden unterstützt: json (JSON-Format), s-exp (s-expressions, S-Ausdrücke), opensearch (ein XML-Format für Suchergebnisse, s. https:…opensearch). Im HTML-Format wird eine minimale HTML-Seite zurückgegeben, in der die einzelnen Suchergebnisse mit semantischen Klassen ausgezeichnet sind. Beispiel:
<div class="semser"> <p class="semser"> <span class="rank">1.</span> <span class="score">+++ 100%</span> <span class="source">(SEM)</span> <div class="semsnippet">Die Faszination <span class="ans">Dom</span> ...</div> <span class="metaname">Artikel: </span><a href="https://..." target="_blank">Faszination Dom</a> ... ggf. weitere Metadaten </div><div class="semserend"></div>
Dasselbe Ergebnis im JSON-Format (oformat=json):
{
"rank": 1,
"score": "100",
"snippet": "Die Faszination Dom ...",
"title": "Faszination Dom",
"url": "https://...",
}
Und als S-Ausdruck (oformat=s-exp):
( (rank 1) (score "100") (snippet "Die Faszination Dom ...") (title "Faszination Dom ") (url "https://...") )
Das Ergebnis zeigen wir nicht als opensearch, da dieses Format mittlerweile meist zu unflexibel ist. Formate können gern verfeinert oder neu vereinbart werden.
2.4.1.11 Zeichensatzkodierung Die API verwendet per Default UTF-8 für die Eingabe und die Ausgabe. Andere Kodierungen können auf Nachfrage über spezielle Parameter eingestellt werden oder bei der Dokumentenkollektion hinterlegt werden.
2.4.1.12 Trefferformat Das inhaltliche Format der einzelnen Treffer wird momentan beim Einrichten der Suchmaschine festgelegt. Es kann (noch) nicht als Parameter übergeben werden.
2.4.1.13 Navigationsformat Falls die Dokumentenkollektion Facetten definiert, wird zu jedem Suchergebnis (API-Kommando sempria-search) auch ein Navigationsblock geliefert. Für das Format oformat=html ist es ein HTML-Fragment, das im Browser geeignet angezeigt werden kann. Für andere Werte von oformat ist das genaue Format noch zu spezifizieren.
Sofern für die Dokumentenkollektion freigeschaltet, findet man ein einfaches Webformular zum Abschicken von Suchanfragen unter folgender URL: https://finde.maschine/sempria? Es dient meist dem Testen oder Debuggen der Suchmaschine.
Zu jeder SEMPRIA-Search als SaaS gibt es einen Hilfetext unter folgender URL: https://finde.maschine/sempria-help?corpus=IHRE-CORPUS-ID&format=htmlfrag Als Ergebnis bekommt man ein HTML-Fragment zum Einbinden an geeigneter Stelle. Weitere Formate auf Anfrage sind html und txt.
Der Index der Suchmaschine wird in den meisten Fällen in regelmäßigen, vereinbarten Abständen aktualisiert. Wenn eine Echtzeit-Aktualisierung mit Sitemap vereinbart wurde, kann die Aktualisierung mit dem Aufruf sempria-update-index asynchron angestoßen werden. Die Laufzeit der Aktualisierung hängt stark vom Umfang der geänderten Daten ab. Beispiel-Aufruf: https://finde.maschine/sempria-update-index?corpus=IHRE-CORPUS-ID Dieser API-Aufruf ist ohne die Parameter pw und corpus nicht möglich. Der Rückgabewert ist 0, falls die Aktualisierung erfolgreich angestoßen wurde, sonst der Fehlercode 1.
Das Kommando sempria-indexed liefert die URLs aller momentan indexierten Dokumente zurück. Beispiel-Aufruf: https://finde.maschine/sempria-indexed?corpus=IHRE-CORPUS-ID Dieser API-Aufruf ist ohne die Parameter pw und corpus nicht möglich. Der optionale Parameter oformat beschreibt das Ausgabeformat. Unterstützt werden hier html und htmlfrag. Auf Anfrage auch json und s-exp.
Wenn SEMPRIA-Search als Plugin integriert wird (z.B. für das Content-Management-System Joomla), dann enthält das Plugin bereits Code und Anweisungen für interaktive Suchvorschläge.
Wenn kein Plugin genutzt wird, dann ist folgendes Vorgehen empfohlen. Zur Einbindung interaktiver Suchvorschläge für Ihre SEMPRIA-Search stellen wir AJAX-Code als JavaScript zur Verfügung. (Falls Sie ein Testsystem bestellt habe, dann ist der Code im Testsystem bereits integriert.) Der vollständige Code umfasst folgende JavaScript-Datei: https://…ajaxSuggSemp.js. Als 2. muss auch etwas CSS-Code integriert werden: https://…sempria-suggest.css Und als 3. und letztes muss Ihr Suchformular erweitert werden. Das Eingabefeld mit id=sentence muss folgende Klasse zugewiesen bekommen:
class="ajax-suggestion url-https://finde-maschine/hop/ sempria/search-suggestions-html?client=IHRE-CORPUS-ID"
Im Formular muss auch ein Bereich zum dynamischen Einblenden der Suchvorschläge definiert werden, z.B.
<div id='search-result-suggestions'><br>Vorschläge <br>1. ggf. unten auswählen <br>2. ggf. oben anpassen <br>3. ENTER-Taste oder Knopf 'Suche starten'<br> <div id='search-results'></div></div>
Wichtig ist die Verwendung der beiden id-Werte in getrennten div-Elementen. Der Hilfetext kann beliebig angepasst werden.