Zoekstrategieën

Alle API's op dit portaal — Auteurs, Beeldbank, Besluiten, Geozoekdiensten, Inventaris, Premieaanvragen en Toelatingen beschermd erfgoed aanvragen — filteren en doorzoeken hun collecties op dezelfde manier. Ken je deze conventie, dan werkt zoeken op elke API van Onroerend Erfgoed hetzelfde. Veldnamen zelf (zoals gemeente of kleur in de voorbeelden hieronder) zijn wel specifiek per API — check daarvoor de eigen Swagger/OpenAPI-documentatie van de API in kwestie.

Algemene regels

• Zoekparameters zijn hoofdletterongevoelig.
• Een lege waarde wordt genegeerd — de collectie wordt er niet door verkleind.
• Onbekende parameters worden genegeerd, nooit geweigerd (zo blijven bv. UTM-tags in een gedeelde link mogelijk).
• Een collectie zonder zoekparameters geeft altijd alle items terug.
• Een ongeldige waarde voor een gekende parameter geeft een 400 Bad Request.

Filteren vs. full-text zoeken

Een collectie verkleinen kan op twee manieren:

• Filteren — exact matchen op de inhoud van een veld, bv. gemeente=Gent. Een item voldoet wel of niet; er is geen "meer of minder relevant".
• Full-text zoeken — zoeken naar hoe goed een item aansluit bij een idee, bv. "Renaat Braem". Resultaten worden gerangschikt op relevantie in plaats van simpelweg gefilterd.

Beide kunnen samen gebruikt worden: full-text zoeken gebeurt dan binnen de collectie die overblijft na het filteren. De voorbeelden hieronder zijn illustratief en gebruiken een fictieve collectie dingen — de syntax werkt identiek op elke echte collectie van een van onze API's, bv. beschermd erfgoed bij Inventaris of aanvragen bij Premieaanvragen.

Filters combineren

Wat	Syntax	Voorbeeld
EN (verschillende velden)	geef meerdere parameters op	?gemeente=Gent&kleur=groen
EN (zelfde veld)	herhaal de parameter	?kleur=groen&kleur=rood (groen én rood)
OF	lijst tussen vierkante haken	?kleur=[groen,blauw] (groen of blauw)
NIET	minteken voor de waarde	?kleur=-oranje

Twee verschillende parameters met OF combineren (bv. gemeente=Gent OF kleur=groen) kan op geen enkele van onze API's — dat is zelden een zinnige vraag en zou de server onnodig kunnen belasten.

Soorten filters

• Booleaanse filters — waarden zoals true/false, 1/0, ja/nee, aan/uit worden hoofdletterongevoelig herkend.
• Objectfilters — verwijzen naar een gekoppeld object via id, uri of label. Welke van de drie je gebruikt, is niet af te leiden uit de parameternaam: ?gemeente=Gent en ?gemeente=44021 geven hetzelfde resultaat.
• Tekstfilters — dragen het achtervoegsel _tekst (bv. schrijver_tekst=Van Daele) en doorzoeken een tekstveld op een patroon, in tegenstelling tot de bijhorende objectfilter (schrijver=<uri>) die exact matcht op één gekoppeld object.
• Datum-/tijdfilters — volgen zoveel mogelijk ISO 8601, inclusief de uitbreiding voor onvolledige en historische datums.

Full-text zoeken

Onze API's zijn allemaal Nederlandstalig, dus waar full-text zoeken ondersteund wordt, gebeurt dat via de parameter tekst.

Wat	Syntax	Voorbeeld
bevat woord	woord	tekst=Gent
EN	&	tekst=Gent & groen
OF	|	tekst=Gent | groen
NIET	-	tekst=-Gent
exacte frase	"..."	tekst="groene rand"
postfix wildcard	*	tekst=Gen* (vindt Gent én Genk)
groeperen	(...)	tekst=(-groen & Brugge) | Leuven

Enkele aandachtspunten:

• Woorden zonder operator ertussen worden automatisch met & gecombineerd: tekst=Gent groen is gelijk aan tekst=Gent & groen.
• Een prefix-wildcard (bv. *ent) bestaat niet, enkel een postfix-wildcard.
• Woorden worden automatisch herleid tot hun stam (stemming): zoeken naar werken vindt ook documenten met werkte of werkt.
• Bij combinaties geldt de volgorde NIET > EN > OF. Gebruik haakjes om dit expliciet te maken, bv. -groen & (Brugge | Leuven).

Filters en full-text combineren

?tekst=Gent&gemeente=-Gent

Zoekt naar het woord "Gent" in alle dingen die niet in de gemeente Gent liggen.

Sorteren

Sorteren gebeurt via de parameter sort: een kommagescheiden lijst van veldnamen. Een - voor een veldnaam sorteert aflopend, een + (of niets) oplopend.

?gemeente=Gent&sort=straat,-huisnummer

Bij full-text zoeken is sorteren altijd ondersteund, en is relevantie een geldige sorteerwaarde: dit sorteert van meest naar minst relevant en kan niet omgekeerd worden. Zonder expliciete sort wordt bij full-text zoeken automatisch op relevantie gesorteerd.