Suchergebnisse

/api/search.json führt dieselbe Suche durch wie die Suchmaske (siehe Zoeken) und gibt das Ergebnis in einer einzigen Antwort zurück, anstatt es während der Suche anzuzeigen. Die Adresse kann ohne Konto und ohne Schlüssel abgefragt werden.

Parameter

• q: der Suchbegriff. Obligatorisch; fehlt er, gibt die Adresse den Status 400 zurück;

• mode ist einer von vier Werten. Fehlt er, gilt „all“:

  • all: Jedes Wort kommt im selben Text vor (der Standard);
  • any: Mindestens eines der Wörter kommt vor;
  • near: Jedes Wort steht innerhalb von zehn Wörtern vom anderen;
  • exact: Die Wörter stehen zusammen und genau in dieser Reihenfolge.

  Was die vier sonst noch bedeuten und wie eine Quelle ohne eigenes „oder“ oder „Nähe“ behandelt wird, steht unter Zoeken;

• page_size: 100, 500, 1000 oder max (der von der Quelle festgelegte maximale Wert). Fehlt dieser Wert, gilt der für diese Installation festgelegte Standardwert 100, es sei denn, der Administrator hat BesluitBron:Search:PageSize geändert;

• date_from, date_to: Die Grenzen des Datumsfilters, in der Form jjjj-mm-dd. Ein leerer Grenzwert lässt diese Seite offen;

• date_undated: 1, um ein Ergebnis ohne Datum anzuzeigen, solange der Datumsfilter aktiviert ist, also solange date_from oder date_to eingestellt ist. Ohne eine der beiden Einschränkungen hat dieser Parameter keine Wirkung: In diesem Fall ist der Filter ohnehin nicht aktiviert und jedes Ergebnis wird berücksichtigt, mit oder ohne Datum. Die Funktionsweise ist unter Zoeken unter „Nach Datum filtern“ beschrieben;

• culture: Die Sprache der Suchergebnisse, der Anmerkungen und der Anleitung richtet sich nach der Quelle, zum Beispiel de. Fehlt diese Angabe, richtet sich die Sprache nach dem Sprach-Cookie des Anfragenden, andernfalls nach Accept-Language.

Ein ungültiger Wert ist ein Fehler, kein stillschweigender Rückfall

Seit Version 1.3.86 gibt die Adresse den Status 400 zurück, sobald mode, page_size, date_from oder date_to einen Wert enthält, der nicht in der obigen Liste aufgeführt ist, zusammen mit einem Feld „error“, das angibt, um welchen Parameter es sich handelte, und einem Feld „error_description“, das die zulässigen Werte auflistet. Beispielsweise führen sowohl mode=xxx als auch page_size=250 zu einer eindeutigen Fehlermeldung, anstatt stillschweigend auf den Standardwert umzuschalten. Das unterscheidet sich vom Suchbildschirm selbst: Dort fällt ein ungültiger Wert in der Adressleiste auf den Standardwert zurück, da ein Besucher eine eingegebene Adresse selten genau liest und eine Fehlermeldung dort nichts löst. Ein Programm, das diese Adresse aufruft, kann einen eigenen Fehler jedoch beheben; daher wird ihm der Fehler angezeigt, anstatt dass stillschweigend eine Korrektur vorgenommen wird, die auf einer Vermutung darüber basiert, was beabsichtigt war.

Was die Adresse zurückgibt

Eine Antwort mit dem Suchbegriff, den einzelnen Wörtern, der gewählten Methode, der Dauer und – pro Quelle – dem Ergebnis, der Anzahl der Treffer, der von der Quelle selbst angegebenen Gesamtzahl sowie der Angabe, ob es sich bei dieser Gesamtzahl um eine Zählung oder eine Schätzung handelt. Die Quellen sind alphabetisch aufgelistet, nicht in der Reihenfolge, in der sie geantwortet haben: Diese Adresse liefert das Suchergebnis, sobald es fertig ist, daher gibt es keine Reihenfolge nach Eingang, die gespeichert werden müsste.

Jede Quelle liefert höchstens die Anzahl, die page_size anfordert – dieselbe Grenze, die auch der Bildschirm selbst anwendet. Wenn page_size mehr anfordert, als eine Abfrage der Quelle liefert, ruft diese Adresse ab Version 1.3.86 selbst mehrere Seiten von dieser Quelle ab, bis die angeforderte Anzahl erreicht ist oder die Quelle nichts mehr zu bieten hat.

Eine Quelle kann eine eigene, feste Grenze haben, die kein „page_size“ erhöhen kann: OpenTK liefert beispielsweise niemals mehr als 280 Treffer für eine Suchanfrage. Ist dies der Fall, steht ab Version 1.3.86 in der Antwort zu dieser Quelle „at_absolute_ceiling: true“: keine höhere page_size und keine weitere Abfrage liefert dort zusätzliche Ergebnisse.

Das gemeinsame Budget

Diese Adresse teilt sich das Kontingent von einer Suchanfrage pro Sekunde mit dem Suchbildschirm, da beide dieselben Quellplattformen abfragen. Ist dieses Kontingent aufgebraucht, antwortet die Adresse mit dem Status 429 und einem Feld „Retry-After“, das angibt, wie viele Sekunden gewartet werden muss.

Was erfasst wird

Ein Aufruf dieser Adresse wird genauso protokolliert wie eine Suchaktion auf dem Bildschirm: eine Zeile pro Quelle im Aufrufprotokoll unter der Kategorie „SEARCH“. Siehe Privacy en Cookies.