Search strategies
Every API on this portal — Auteurs, Beeldbank, Besluiten, Geozoekdiensten, Inventaris, Premieaanvragen, and Toelatingen beschermd erfgoed aanvragen — filters and searches its collections the same way. Learn this convention once, and search works the same on every Onroerend Erfgoed API. Field names themselves (like gemeente or kleur in the examples below) are specific to each API — check that API's own Swagger/OpenAPI docs for those.
General rules
- Search parameters are case-insensitive.
- An empty value is ignored — it does not narrow the collection.
- Unknown parameters are ignored, never rejected (this is what keeps things like UTM tags on a shared link working).
- A collection queried without any search parameters always returns every item.
- An invalid value for a known parameter returns a
400 Bad Request.
Filtering vs. full-text search
There are two ways to narrow down a collection:
- Filtering — an exact match on a field's content, e.g.
gemeente=Gent. An item either matches or it doesn't; there's no "more or less relevant". - Full-text search — searching for how well an item matches an idea, e.g. "Renaat Braem". Results are ranked by relevance rather than simply filtered.
Both can be combined: full-text search then runs over whatever remains of the collection after filtering. The examples below are illustrative and use a fictional dingen ("things") collection — the syntax works identically on any real collection from one of our APIs, e.g. protected heritage at Inventaris or applications at Premieaanvragen.
Combining filters
| What | Syntax | Example |
|---|---|---|
| AND (different fields) | pass multiple parameters | ?gemeente=Gent&kleur=groen |
| AND (same field) | repeat the parameter | ?kleur=groen&kleur=rood (green and red) |
| OR | a list in square brackets | ?kleur=[groen,blauw] (green or blue) |
| NOT | a minus sign before the value | ?kleur=-oranje |
Combining two different parameters with OR (e.g. gemeente=Gent OR kleur=groen) isn't supported on any of our APIs — that's rarely a meaningful query and could put unnecessary load on the server.
Types of filters
- Boolean filters — values like
true/false,1/0,yes/no,on/offare recognized case-insensitively. - Object filters — reference a linked object via
id,uri, orlabel. Which of the three you use can't be inferred from the parameter name:?gemeente=Gentand?gemeente=44021return the same result. - Text filters — carry the
_tekstsuffix (e.g.schrijver_tekst=Van Daele) and search a text field for a pattern, unlike the corresponding object filter (schrijver=<uri>), which matches exactly one linked object. - Date/time filters — follow ISO 8601 as closely as possible, including the extension for incomplete and historical dates.
Full-text search
All of our APIs are Dutch-language, so wherever full-text search is supported, it's through the parameter tekst.
| What | Syntax | Example |
|---|---|---|
| contains word | word | tekst=Gent |
| AND | & | tekst=Gent & groen |
| OR | | | tekst=Gent | groen |
| NOT | - | tekst=-Gent |
| exact phrase | "..." | tekst="groene rand" |
| postfix wildcard | * | tekst=Gen* (matches both Gent and Genk) |
| grouping | (...) | tekst=(-groen & Brugge) | Leuven |
A few things to note:
- Words with no operator between them are automatically combined with
&:tekst=Gent groenis the same astekst=Gent & groen. - A prefix wildcard (e.g.
*ent) doesn't exist — only a postfix wildcard is supported. - Words are automatically reduced to their stem (stemming): searching for
werkenalso finds documents containingwerkteorwerkt. - Combinations follow the precedence NOT > AND > OR. Use parentheses to make this explicit, e.g.
-groen & (Brugge | Leuven).
Combining filters and full-text search
?tekst=Gent&gemeente=-Gent
Searches for the word "Gent" among all things that are not located in the municipality of Gent.
Sorting
Sorting uses the sort parameter: a comma-separated list of field names. A - before a field name sorts descending, a + (or nothing) sorts ascending.
?gemeente=Gent&sort=straat,-huisnummer
When full-text search is used, sorting is always supported, and relevantie ("relevance") is a valid sort value: it sorts from most to least relevant and can't be reversed. Without an explicit sort, full-text search results are sorted by relevance automatically.