Most of this release is under the hood rather than user-visible, focused on stability. One new user-facing feature: a simple tree view that makes printing a thesaurus practical.

The breaking change concerns how and when skosprovider.registry.Registry gets instantiated: previously this happened at application startup, now it happens per request. The old approach caused problems with SQLAlchemy providers on a multi-threaded webserver. See the customisation docs for the new pattern, and the pyramid_skosprovider docs for background.

Python 2 support is being phased out across the whole stack:

• atramhasis will drop it in 1.0.0
• skosprovider will drop it in 0.8.0
• language-tags dropped it in 1.0.0
• pyramid_skosprovider will drop it in 0.10.0
• skosprovider_sqlalchemy will drop it in 0.7.0
• skosprovider_atramhasis dropped it in 0.4.0
• skosprovider_getty will drop it in 0.6.0
• skosprovider_rdf will drop it in 0.9.0
• skosprovider_heritagedata is currently unmaintained

SKOS collections also got a fix: it was always assumed that concepts in a collection are narrower concepts of that collection's superordinate concept, but the implementation was incomplete and buggy. Collections now have a boolean infer_concept_relations attribute — when true, member concepts count as narrower concepts of the superordinate; when false, they don't. This mainly affects a provider's expand function and how thesaurus arrays or node labels are interpreted.

We also invested in SEO: concept detail pages now carry HTML metadata such as a canonical URL, a Twitter card and OpenGraph info, and a new script can generate an XML sitemap for your installation.

The Atramhasis admin interface

If you're not sure what Atramhasis looks like or does, the documentation now has a dedicated features section explaining it.

As always, see the 0.7.0 release notes for the full changelog. Try a live example at thesaurus.onroerenderfgoed.be. Questions or issues: the forum or our GitHub tracker.

At Flanders Heritage Agency we've tried, for a long time now (since roughly 2005), to keep our URIs as stable as possible. When a URL has to change or disappear anyway, we set up a redirect from the old URL to a page with the same or similar information. So you can still browse the inventory via https://inventaris.vioe.be, even though https://inventaris.onroerenderfgoed.be has been the canonical URL for years, and https://www.erfgoed.net/beschermingen still sends you to the search form for protected heritage, even though that original page hasn't existed for nearly a decade.

The downside: many people don't realise URLs have changed, and old URLs linger on all kinds of websites, redirecting to newer ones. The longer that goes on, the more tangled the redirect logic gets — old URLs pointing to less-old URLs, which in turn redirect to current ones. Once the memory of those old systems fades, it also gets harder for us to keep everything working. So today we're listing a number of common old links, focused on protected heritage (the inventory itself is covered in a later post).

Information systems for protected heritage​

Long before the web was really a thing, there was already a first information system for protected heritage: Melanie, short for Monumenten En LANdschappen InformatiEsysteem. Initially not connected to the internet at all, it later got an online view of the protected objects in a shadow database. Even without URIs, every protected object already got a unique number following a fixed pattern: an O (for "object"), a letter per province (W, O, A, L, B), and six digits between 000000 and 999999 — the Melanie Object Number, such as OO003255 or OW000678. You'll still spot these on today's designation-object records. There were also Melanie Dossier Numbers, structured the same way but starting with D instead of O, since multiple objects could be protected together in one dossier — like DA002378, covering 4 protected monuments by 1 architect.

When Monumenten en Landschappen merged into the Ruimte en Erfgoed agency, its information systems were merged too. Melanie was retired, and its role taken over by Bredero, the case-tracking system already used for Spatial Planning. It also had the concepts of an object and a dossier. A Bredero number has three parts separated by slashes: the document type (protected monument, townscape, protection dossier, ...), a 5-digit NIS code for the municipality or province, and a sequence number. A full number looks like 4.01/43005/162.1 (a protected monument), 4.03/40000/107.1 (a protected landscape), or 4.001/30000/2517.1 (a protection dossier).

When Flanders Heritage Agency was founded in 2011, it quickly became clear that Bredero was well suited to case tracking, but not to a stable environment for detailed, object-related heritage information. The existing Flanders Heritage Inventory offered far more there, and that synergy produced the designation objects (see Heritage objects and designation objects). When building that dataset, we carried over the old identifiers as much as possible, which is why a designation object's page still lists older numbers today under Beschermingsdossiers. The inventory itself had always lived on the web and always used URIs, and since designation objects came about, we've followed the Flemish Government's URI guidelines. So you can find the parish church of St. Peter and St. Paul in Hansbeke under the old Melanie number OO001175, the equivalent Bredero number 4.01/44049/119.1, and the new URI https://id.erfgoed.net/aanduidingsobjecten/10535.

Searching by Melanie or Bredero number on the designation objects search form

The protection-database project included migrating protected objects from Bredero into designation objects, with close attention to data quality, a re-evaluation of old data, and the addition of new information such as location data and thesaurus terms. Sometimes an old Melanie or Bredero number had to be split across several new records, so today one old number can occasionally map to more than one record — the exception rather than the rule. To make this easy, you can just search on an old number: go to the designation objects search form and enter the Melanie or Bredero number under Ander nummer? ("other number?") at the bottom.

Old URLs​

If you still have an old URL lying around somewhere, it will always contain a Melanie or Bredero number. URLs from 2012–2016 probably look like https://beschermingen.onroerenderfgoed.be/object/id/OO001175 or https://beschermingen.onroerenderfgoed.be/object/id/4.01/44049/119.1. After 2016 that traffic was redirected to an inventory page such as https://inventaris.onroerenderfgoed.be/erfgoed/beschermd/OO001175, showing every linked designation object (or redirecting straight through if there was only one). Today that traffic goes to something like https://inventaris.onroerenderfgoed.be/aanduidingsobjecten?ander_nummer=OO001175, showing every designation object matching that old number.

If you have even older URLs like http://paola.erfgoed.net/engine/fiche.php?id=000816&pv=O, those no longer work, but you can easily reconstruct the Melanie number: take the value of pv, followed by O, followed by the value of id — giving OO000816, which you can then look up under "other number" in the new inventory. That eventually leads you to the Motte de Hoge Wal in Ertvelde.

If you have old links, we strongly recommend converting them to our new URIs. Note the distinction between the document URI (say, the page you can read about the Hoge Wal) and the concept URI (representing the concept of the Hoge Wal as a tangible object). We only guarantee persistence on the latter: the document URI is tied to our domain name onroerenderfgoed.be, which is tied to our organisation's name, while the concept URIs on erfgoed.net aren't affected by that.

Say it with a script​

If you have a lot of links to our site, looking them up one by one is a lot of work. So we've put together a short Python script that resolves a whole batch of old Melanie or Bredero numbers to their URIs in one go: save the script, provide a CSV file listing the old identifiers, and run it. The full script is available in this blog's source repository on GitHub.

Pagination. Web scale​

At Flanders Heritage we've started aligning our information systems with this standard, particularly the pagination building block. For now we're adopting the HTTP Link header method of pagination, as specified here and detailed in RFC 5988.

To see this in action, look at the Link HTTP header — via a command-line tool like cURL, a browser plugin, or a standalone REST client. We'll use cURL, since it's generally available or easy to install on Linux and Mac.

Say we're interested in books and documents about Knokke, a coastal town in Flanders. Looking at the REST API docs at https://bib.onroerenderfgoed.be/api_docs tells us we can call https://bib.onroerenderfgoed.be/werken with a titel parameter, so https://bib.onroerenderfgoed.be/werken?titel=knokke gives us books with Knokke in the title, or a chapter title:

$ curl -G -i -H Accept:application/json https://bib.onroerenderfgoed.be/werken?titel=knokke
HTTP/1.1 200 OK
Date: Mon, 16 Dec 2019 19:51:07 GMT
Server: Apache
Content-Type: application/json
Content-Length: 3933
Access-Control-Expose-Headers: Content-Range, X-Content-Range
Accept-Ranges: items
Content-Range: items 0-9/167
Link: <https://bib.onroerenderfgoed.be/werken?titel=knokke&per_pagina=10&pagina=2>; rel="next", <https://bib.onroerenderfgoed.be/werken?titel=knokke&per_pagina=10&pagina=17>; rel="last", <https://bib.onroerenderfgoed.be/werken?titel=knokke&per_pagina=10&pagina=1>; rel="first"
X-Content-Type-Options: nosniff
Access-Control-Allow-Origin: *
X-Permitted-Cross-Domain-Policies: none
X-XSS-Protection: 1; mode=block

[{"publicatietype": {"url": "http://purl.org/ontology/bibo/Document", "naam": "Document", "id": 1}, "titel": "Het landelijke Knokke", "self": "https://bib.onroerenderfgoed.be/werken/552291", "uri": "https://id.erfgoed.net/infocat/werken/552291", "auteur": "D'hont A.", "id": 552291}, "... 9 more results ..."]

This curl call fetches books and documents (werken) from our library catalog with knokke in the title, and asks it to print the headers. The one we care about here is Link:

Link: <https://bib.onroerenderfgoed.be/werken?titel=knokke&per_pagina=10&pagina=2>; rel="next", <https://bib.onroerenderfgoed.be/werken?titel=knokke&per_pagina=10&pagina=17>; rel="last", <https://bib.onroerenderfgoed.be/werken?titel=knokke&per_pagina=10&pagina=1>; rel="first"

We got results back, but only a partial set. The Link header tells us there's a next page, a last page and a first page — and since we're on page 1, no previous. We can follow these links to page through the results, or jump straight to the end. Importantly, a client shouldn't assume anything beyond what the links say: you might be tempted to infer, from 17 pages of at most 10 records each, that there are 161–170 results, but the server isn't obliged to make that arithmetic hold, or to put any other information in the link. This does expose a real limitation of Link-header pagination: there's no way to tell how many results there are in total, or how many pages remain. All the client knows is whether there's a next link; if there isn't, you're on the last page, and if next and last are identical, you're on the second-to-last. On the upside, the client needs zero knowledge of the URL's internal structure — no page vs. pagina, no limit/offset — which makes it easy to reuse the same client code across very different webservices. All it needs to know is: if there's a next link, there's more to fetch.

To get the second page:

$ curl -G -i -H Accept:application/json https://bib.onroerenderfgoed.be/werken?titel=knokke\&per_pagina=10\&pagina=2

All your data belongs to us!​

To show this off, we wrote a small Python script that queries several of our information systems and handles pagination via the Link header automatically. In Python, the requests library is the standard tool for REST calls, and conveniently it already has built-in support for the Link header, making it trivial to iterate over every result. For this example, we fetch all images (see Searching the image database), themes (see Themes, people and events), heritage and designation objects (see Heritage objects and designation objects) for the municipality of Knokke-Heist. It's a short script that drops a large pile of URIs at your feet, chaining calls to the various APIs and following each next link along the way.

Running it prints a long list of URIs — functional, but not exactly satisfying: a URI is great for a machine, but doesn't tell a human much on its own.

No context, no information​

Another interesting technique in the Linked Data world is JSON-LD (JSON for Linking Data), which turns plain JSON into linked data by mapping it to RDF through a context — defining which JSON keys correspond to which RDF properties. Here's a simple context you could use on our image database endpoint:

{
    "dct": "http://purl.org/dc/terms/",
    "title": "dct:title",
    "description": "dct:description",
    "uri": "@id"
}

This defines a namespace shorthand dct for the Dublin Core Terms namespace, so dct:title stands in for the full http://purl.org/dc/terms/title, and maps uri to @id, JSON-LD's way of marking a record's unique identifier. Applying this context to an image from our image database gives:

{
    "@id": "https://id.erfgoed.net/afbeeldingen/392715",
    "http://purl.org/dc/terms/title": "Villa Cools met kinesistenpraktijk",
    "http://purl.org/dc/terms/description": ""
}

This tells us there's a resource identified by https://id.erfgoed.net/afbeeldingen/392715 that can be described with a Dublin Core title. It's common in JSON-LD to also assign a @type, a URI pointing to a class in an RDF vocabulary, so records from different sources stay distinguishable once merged:

{
    "@id": "https://id.erfgoed.net/afbeeldingen/392715",
    "@type": "http://purl.org/dc/dcmitype/Image",
    "http://purl.org/dc/terms/title": "Villa Cools met kinesistenpraktijk",
    "http://purl.org/dc/terms/description": ""
}

Once more, with feeling​

Let's use JSON-LD to improve our script. We want a homogeneous dataset covering everything known about Knokke-Heist, with every record sharing the same structure — so we built two JSON-LD contexts, one for the image database and one shared across the three closely related inventory datasets. Since none of these datasets normally include their own resource type, we add that ourselves. Our inventory system also has a locatie_samenvatting field summarising an object's geographic location — the underlying summarisation logic can get fairly involved (some things sit in more than one street, municipality or even province), but it's very handy for a human glancing at results. The image database has no such field, so we compute a simple equivalent for it (image locations are much simpler than those of heritage objects).

The script fetches everything as before, adds the record type and a location summary for images, then expands it all into JSON-LD using the Python pyLD library. That leaves us with valid but unwieldy JSON-LD — every key is now a URI. So we compact it again, using a third context based on Dublin Core Terms, and print the result.

To run this script, install requests and pyLD first. It may take a while for larger municipalities like Gent or Antwerpen. As a bonus, we also wrote a variant that writes the resulting dataset to a CSV instead of printing it — feel free to adapt either script to build your own dataset for another municipality.

If Hypermedia APIs and Linked Data interest you, https://data.vlaanderen.be/ has a lot more background and points to the relevant standards and documents, and there's a whole community of Linked Data people happy to answer questions — you'll find a fair number of them on Twitter. As always, feel free to get in touch with further questions.

The Flanders Heritage geoportal in 2014

Our first and main requirement was something easy to use for a large user base. We'd noticed that other geoportals tended to cater to GIS professionals, often building what amounted to an online desktop GIS — versatile and powerful for people who already know GIS, but inaccessible to everyone else. We wanted an experience closer to Google Maps, tailored specifically to people looking for cultural heritage information in Flanders. We also wanted the geoportal to feel like part of our online information systems, not a separate geodata silo, so we built reports that link back to our online sources through their persistent URIs. Those URIs live as metadata in all our geographical data, tying every feature back to the authentic source application the raw data (geodata included) lives in — so you can always follow the link to see the full set of attributes and everything we know about a resource.

The Flanders Heritage geoportal in 2019

A second requirement came from the data itself. Flanders Heritage creates and publishes geodata about immovable heritage, but not other kinds of geodata, and we didn't want to start doing so just for the geoportal — so we lean heavily on publicly available webservices instead. Informatie Vlaanderen (formerly AGIV) has always been our partner for basemaps and non-heritage layers, and we've pulled in other layers too, from bodies like Mercator or other countries' agencies (e.g. the Dutch Cultural Heritage Agency). Informatie Vlaanderen also provides alphanumeric services that help navigate maps: the CRAB service enumerating Flemish address data, the CAPAKEY service for cadastral parcel data, and a geolocation service for free-text address search. We wanted to use these services, not copy their data wholesale, as might have happened a decade earlier — we store as little as possible from them, a cache here and there at most, so what we show users always matches the source.

Finally, from a technical standpoint, we wanted open source software (cost-efficient, and a good fit for our stack) and a portal that's simple to maintain while still configurable in detail — easy things (adding a data source) should be easy, hard things (optimising specific requests) should be doable. That philosophy has served us well: a fairly light codebase has kept serving our visitors for years.

Software architecture of the Flanders Heritage Geoportal

So where did those design considerations land us? Like any modern application, the geoportal has a back- and a frontend. The frontend is the bulk of the code (roughly 98% JavaScript, HTML and CSS) — the map layout, UI/UX and general presentation. Since it was written several years ago, it still runs on an older JavaScript framework, Dojo, with OpenLayers (and PROJ4) for mapping, and HTML/CSS built on the Flemish government's corporate style using the Zurb Foundation framework. The frontend talks exclusively through services, either to our own geoportal backend or to other webservices.

Those other services are mostly INSPIRE-compliant WMS, WMTS and WFS services hosted across a few parties:

• Informatie Vlaanderen hosts a large number of reference datasets — basemaps, aerial photography, historic maps, address data, cadastral parcels — through the official Flemish INSPIRE node.
• Mercator is an INSPIRE subnode hosting datasets for the Environment policy domain, a cluster of Flemish Government entities covering topics like Environment, Pollution, Energy, Heritage and Spatial Planning. Flanders Heritage publishes its own INSPIRE-compliant heritage data through this subnode.
• While end users typically harvest our layers via Mercator, for our own geoportal we run our own Geoserver instance, giving us more control over presentation and letting us keep a few internal or authenticated-only layers unpublished.
• We've also included Dutch INSPIRE heritage layers from our colleagues at the Cultural Heritage Agency — heritage doesn't respect political borders, so it's useful for our users to see across them, and consuming another party's published WMS is easy.

We also use a few non-INSPIRE layers: OpenStreetMap as a solid general basemap, the NGI topographical map for those interested, and, mostly for fun, the Pelagios map of the Roman World.

The geoportal backend is a simple Python application built on the Pyramid framework. Besides serving the frontend's static files, its main job is proxying a few location services from Informatie Vlaanderen:

• Geolocation, suggesting addresses from free-text input and returning coordinates — a quick way to navigate the map.
• CRAB, a more exhaustive service with full address data (municipalities, streets, house numbers and their locations). We use it across most of our systems to validate incoming data; in the geoportal it's a navigational aid, letting users drill down from province to municipality to street to address.
• CAPAKEY, a REST service with parcel data (municipalities, cadastral divisions, sections and parcel numbers), similarly used to guide users through the Belgian cadastral system to a specific parcel.

These three services are now freely and openly available, so proxying them might seem less necessary than it did when we started in 2013:

• Early on, both CRAB and CAPAKEY were SOAP services, hard or impossible to call directly from browser JS. CAPAKEY has since moved to REST, but CRAB is still SOAP. Both also originally required authentication, so proxying let us shield the credentials.
• It frees us from wrestling with CORS headers — we already use CORS a lot, but getting it all to cooperate can be a hassle, and the Geolocation service doesn't support CORS at all, which would otherwise force us into something like JSON-P.
• It insulates us from upstream API changes: since our applications always call our own proxies, only the proxy needs to track an upstream change (like CAPAKEY's SOAP-to-REST move), keeping the impact on our systems minimal and contained.
• The CRAB and CAPAKEY proxies double as caches, cutting the number of calls to the upstream services significantly.
• We've extended these services in a few small ways for our own needs — adding a list of Flemish provinces (present in neither CRAB nor CAPAKEY), and incorporating a list of country codes for address validation.

If you need Flemish address or parcel data yourself and work in Python, feel free to use our CRABpy library; if you're on Pyramid, CRABpy_pyramid simplifies integrating it and adds a set of opinionated JSON views on top.

The other major backend component is an open source project called Mapproxy, which solved what was for a while the hardest part of building the geoportal: dealing with non-publicly-accessible spatial data. Our prime example is a database of archaeological findspots that, for several reasons, isn't public — the data isn't part of INSPIRE, but does have WMS/WFS services on our own Geoserver, protected by username and password. Including that service directly in our frontend would expose those credentials to clients; Mapproxy solves this by proxying the service on our geoportal server and handling authentication and authorisation itself, letting us translate the same Pyramid authentication/authorisation policies we use in all our web applications into rules about which GIS layers are visible to whom.

Beyond this security-related proxying, we also route WMS GetFeatureInfo requests through Mapproxy to avoid CORS issues, and may make more use of its caching features down the line, though we haven't yet.

All told, our geoportal has proven to be an important platform, used by roughly 12,000 people a month in fairly intensive sessions, while remaining cheap to build and run — it needs very little in the way of resources itself, since the heavy lifting is done by underlying services shared with other applications and processes. Interested in the setup? Browse the geoportal, check our libraries on GitHub, read more posts tagged geoportaal, or drop us a line at ict@onroerenderfgoed.be.

No innovation without dissemination​

Innovation often brings technology to mind, but society itself is innovating constantly too — sometimes driving technological progress, sometimes following it. One of the past decade's clearest shifts has been toward openness: open source software, open data and open access are central to today's information-driven society. Both Flanders Heritage and the Flemish Government support open data and open access. On the open data side, the government has adopted the Smart Flanders Open Data Charter; Flanders Heritage has published several open datasets, such as our thesauri and controlled vocabularies, under the Flemish open data licence, and we also publish the software used to maintain them as open source.

On scholarly open access, we aim to make all our publications freely available. Nearly all research output is published through OAR, our Open Access Repository. In recent years we've invested in digitising publications by our predecessors, and now have an online archive going back to the eighties, all freely downloadable. Digitisation might sound trivial — scan it, put it online — but copyright and the effort of producing good metadata make it more work than it looks. It's paid off: since digitising and publishing our back catalogue, monthly downloads have doubled, and we now see around 15,000 publications consulted digitally every month.

Number of downloads per month from OAR

Pictures or it didn't happen​

While our publications are still very much a written information channel, visual information matters more and more today. Heritage professionals have documented heritage and its condition ever since cameras existed, and digital cameras — more recently smartphones with good cameras — have only accelerated this. We estimate a few million pictures circulate within our agency, in both analog and digital form. In 2019 we launched a new online image database holding some 280,000 images of heritage in Flanders, some recent, some digitised from analog archive material. Reusability mattered a lot here too: where possible, images are published under an open licence allowing reuse, even commercially, as long as attribution is given.

A set of images in the image database found by searching for "Bijloke"

The system has been running for a while and has proven our basic needs are covered, so we're now tackling more complex problems. First, GDPR and privacy: while our pictures are taken in public places, things like license plates and faces count as sensitive data. We have manual review procedures, but they're slow and labour-intensive, so we're exploring automatic detection and blurring of license plates and faces with OpenCV. Results for license plates have been good; results for faces more mixed, likely because license plates follow a simple, predictable format, while facial detection tends to be a bit too eager — it has a habit of flagging paintings, sculptures or billboards as faces too. More tuning is needed before this is ready for large-scale use.

The license plate on the left was automatically blurred with OpenCV

Another avenue is automated duplicate detection. As in any large organisation, files get copied, distributed and emailed repeatedly, and images end up in multiple places — costing storage and, since every image needs metadata, duplicating that effort too. We're exploring automatic duplicate detection; image hashing looks promising, and we'll likely settle on the dHash algorithm. We're now working out how to integrate this properly into our archiving workflows so colleagues benefit without needing to deal with the technical details — innovation only really pays off once it comes with usability.

As a government agency dealing with immovable cultural heritage, almost everything we collect has a spatial dimension, and our images are no exception. Nearly every picture we take shows some form of immovable heritage — an archaeological site, a cultural landscape, a building, a cemetery, or something else — so we've put real effort into geolocating the images in our database. Older images are linked to the heritage objects they depict and inherit their location; newer images rely on the automatic geolocation built into modern smartphones and cameras. The resulting GIS layer of point locations can be visualised on our geoportal or downloaded for your own use, and every picture links through to the image database for more information, download and reuse — provided you respect the licence.

A view of the Bijloke site in Ghent with all known images of this area

Give me a map and I'll never get lost​

Nearly everything we do has a spatial component, which makes maps essential to us. As a government agency we publish INSPIRE-compliant datasets, distributed through the INSPIRE network across Europe — aimed mostly at professional GIS users on their own desktop software. But we felt we were missing part of our audience: people who just want to quickly find out what's known about their neighbourhood, their property, or a place they remember from childhood. That's why we built our own Geoportal, a website where a regular, non-GIS user can browse a (hopefully) intuitive map of Flanders and see what heritage is present — the aim was something like "Google Maps for Heritage." It's no longer new, but it's still very popular, and because it's optimised for heritage data specifically, it works better for that purpose than a general-purpose portal. For general spatial data we point people to Geopunt, the Flemish Government's geoportal for all spatial data — it holds far more data than we need, but isn't optimised for heritage information specifically.

The current-day city of Zottegem and its listed heritage as seen on the Villaret map (1745-1748)

First-time visitors to the Geoportal are asked to pick one of two profiles — preset combinations of map layers, one a good default for most people, the other tuned for users focused on the legal side of heritage (actuaries, real-estate agents, property developers, other government bodies, and so on). You can always load other layers too. Some point to our other systems, like the image database mentioned above, or archaeological survey reports submitted by archaeologists. Base layers include several orthophoto layers as well as historical maps, some dating back to the 18th and 19th centuries — some supplied by Informatie Vlaanderen, others, like the Villaret map (1745–1748), digitised by us in cooperation with them.

Have a look at our portal, browse the map, and dig into the places and pictures you find there.

When points become clouds of information​

The city of Damme and its fortifications as seen on the multidirectional hillshade

One last mapping project to close with. Our colleagues at Informatie Vlaanderen created the Digitaal Hoogtemodel Vlaanderen (DHMV), a LIDAR dataset consisting of a Digital Surface Model and a Digital Terrain Model, together giving height data that lets us visualise the Flemish terrain in different ways. While the raw data is open, turning it into a useful visualisation takes real expertise, so a few standard renderings have been available for a while. We knew it was possible to create visualisations better suited to archaeologists, allowing easier detection of archaeological sites through micro-topology, so Flanders Heritage and Informatie Vlaanderen collaborated on two new renderings of the DHMV and published them. Each uses different techniques and parameters, so which one helps depends on what you're looking for.

Trenches and a fortress near Kapellen as seen on the skyview factor

The result has proven genuinely useful to archaeologists in their day-to-day work — glancing at these two layers, either on the Geoportal or downloaded into their own GIS, lets them quickly judge the potential of a site or location. To try it, head to the Geoportal and select them under Layers > Background layers > Digital Elevation Model > DHMV II, multidirectional hillshade or DHMV II, skyview factor. This project has been more successful than we expected, and its impact has reached well beyond archaeology and cultural heritage — it was even nominated for a Datanews ICT Project of the Year and an Agoria e-Gov Award Open Data.

We hope this shows there's a real synergy between heritage and technology as we move further into the 21st century. Like every organisation, technology has become deeply woven into our daily operations. As Satya Nadella, Microsoft's CEO, put it: "Every company is now a software company" — and the same holds for a government agency or a cultural heritage institution. Software is everywhere, digital is everywhere, and even though our cultural heritage is still largely analog, the tools and information sources we use to study it no longer are, and never will be again.

Questions? Get in touch, browse the rest of this blog, check out our open source projects, or visit our website.

The image database homepage

On the image database's homepage, a simple search bar at the top lets you search on one or more terms, like any typical search engine. Search for Knokkestraat, for instance, and you get 18 results sorted by relevance — just like the inventory (Full-text search in the inventory), the most "Knokkestraat-like" result comes first: a set of images of houses on Knokkestraat in Knokke-Heist, where the street name appears both in the title and the address. Next come images from Knokkestraat in Diksmuide, Zwevegem and Wachtebeke, where the name is in the title but not the address.

Images matching the search term "knokkestraat", with a few facets

On this results page you can refine using facets: filters on the dataset such as Province, Municipality, Year, Creator and License. Each facet shows every possible value along with a count — so you can see at a glance there are 8 images from Knokke-Heist and just 1 from Diksmuide. The License facet shows the terms under which an image may be reused.

The free-text field supports the same full-text search operators as the inventory:

• Multiple terms are implicitly combined with AND: molen knokke is the same as molen & knokke.
• Use | for OR: molen | knokke.
• Use - right before a term for NOT: molen -knokke.
• Treat multiple words as one term with quotes: search van daele and you get 7 images containing both van and daele, but search "van daele" and you only get images by the photographer of that name.
• Use a postfix wildcard * to search part of a word (only at the end): roze* matches rozendale, rozeveldstraat and rozebeekstraat alike.
• Use parentheses () to group operators: dorp* (knokke-heist | brugge) finds images with a term starting with dorp, combined with either knokke-heist or brugge.

Keep in mind the general search field matches words, which can refer to "a municipality" just as easily as something else — searching brugge* finds both images of bridges (bruggen) and images from the municipality of Bruges (Brugge). Our search engine ranks results by relevance by default: an image where a term appears more often ranks higher, and certain fields (title, location, description) weigh more than others. If you'd rather not have that, change the Sort by field on the results page to title or capture date.

Full-text search combines cleanly with facets: search brugge* and tick the year 2019, and you'll see every 2019 image with a term starting with brugge.

A heritage object in the immovable heritage inventory, with links to the image database

Besides the search form, there are other ways to find images. Most images are linked to the immovable heritage inventory: look up a heritage object there and you'll see a selection of images, with a link to view all of them.

Viewing image database images on the geoportal

You can also use our geoportal, which has an optional Beeldbank layer (off by default, toggle it under Layers). Once enabled, camera icons appear once you're zoomed in far enough; click one to see all images at that location. This layer can also be downloaded and integrated into your own GIS workflow — the attribute table includes a download link for every available format.

So there are several ways to find images in our image database. Just remember to respect the license terms and credit everyone appropriately for their work. Questions or suggestions are welcome at ict@onroerenderfgoed.be.

The people and collectives dataset has existed since the very first inventory launched in May 2009. It holds people and organisations who played a role in creating the heritage we describe: architects, contractors, master builders, clients, artists, sculptors, and so on. The dataset emerged in 2007–2009 while assigning thesaurus terms to heritage objects. Until then, heritage objects were mostly documents, which made searching harder — especially with common surnames, finding "all buildings by a particular architect" was difficult. (Did you know there was once an architect named Baksteen, literally "Brick"?) So alongside the thesauri, we also built an authority file holding canonical versions of the designers and other people involved. For the agency, this dataset — like our thesauri — isn't a core dataset in its own right: without the inventory, we wouldn't need it at all.

Over the years the dataset has grown into a fine cross-section of designers, artists and architects who shaped Flanders' heritage. Where possible we enrich each entry with other known names, birth and death dates (or founding dates for organisations), places lived or worked, professions, education, and a short biography, and we link every person or collective to the heritage objects they're connected to as designer, builder, or client. Our people dataset is, in effect, a quick who's who of Flemish immovable heritage.

The events dataset has also existed since May 2009, though for a long time it was only accessible internally. An event is an action performed at a given moment by one or more people or organisations — in practice, limited to actions on or about immovable heritage. That can be something as small as measuring a tree, an excavation or a site inspection, up to a large project like an inventory campaign. It always comes down to: X and Y performed work of type A at location L, from date I to date J. We sometimes add an extended text description with links to further sources, aiming to explain how a piece of information came about. So for a given heritage object you can see which inventory campaign first recorded it, when it was re-surveyed, and when its address was last checked.

The third dataset, themes, has two subtypes: one that already existed in the 2009 inventory, and one added fairly recently. A theme provides context around heritage objects, so certain information doesn't need to be repeated on every individual object. The first themes, added in 2014, fall under content themes — usually a combination of typology, style or period, and location, such as First World War military defences in the front zone, Welcome trees, or Prehistoric barrow complexes and urnfields. With the launch of the new inventory, older descriptions of geographic areas were converted into geographic themes — the old municipality and street introductions from the Bouwen door de Eeuwen Heen series, which, like the content themes, provide context, but purely based on location. That's where you can read more about the historic core of Ghent, Lippenslaan in Knokke, or the port of Antwerp. Some of these theme pages are among our most-visited, and are often used by outside parties as historical context.

None of these three datasets forms the essence of the immovable heritage inventory, but together they make it more interesting and more useful. Want to know more about the new inventory? Read Ten years of the inventory. Questions or suggestions are welcome at ict@onroerenderfgoed.be.

What was new then is old now​

The new inventory follows the technological principles and architecture Flanders Heritage Agency has used since 2014, following the merger of the Flemish Institute for Immovable Heritage (VIOE) and the Ruimte en Erfgoed agency. At the time, the agency had a very diverse technology landscape, and it was quickly decided to move to a new technology stack.

VIOE already had a strong preference for open source software, and that choice was kept: on the systems side we stuck with *nix servers (Debian or Ubuntu), and on the database side PostgreSQL remained the obvious choice — no licensing cost, ample capacity for our volumes, and with the PostGIS plugin, an excellent GIS engine.

The biggest change was the choice of programming language. Where VIOE had developed in PHP and Ruimte en Erfgoed worked with Java and .NET, the new agency settled on Python. Of the three major Python web frameworks available at the time (Django, Flask and Pyramid), we ultimately went with Pyramid. Elasticsearch was added for fast search over large datasets, and Redis for caches and queues handling asynchronous jobs.

Our frontends have since used a CSS framework like Foundation, and like many other web developers, we made the move to Single Page Applications (SPAs) — web applications running largely on JavaScript, talking to the backend continuously through REST services. We use those heavily for management environments and complex applications like our geoportal; for public-facing pages we deliberately keep things functional with minimal JavaScript, so they work well on older devices and index cleanly for search engines. Our first SPAs used Dojo; more recent applications use Aurelia.

Where the old inventory started out on classic HTML forms and HTTP POST requests, it evolved over the past decade toward a system built around REST services. In the new inventory, as in all our current applications, we followed that through fully: we built a Resource Oriented Architecture, moving from a few large, monolithic applications to a network of smaller, more focused applications each with their own specialisation. The new inventory is now the central component of that network.

Deployment and operations changed just as much: ten years ago we made manual changes on a handful of servers in a single data centre; today we run automated deploys across two data centres, using Ansible for base server setup, fabric for rolling out applications, and Alembic for managing version-controlled database schemas.

It's not just the technology that changes​

Technology wasn't the only thing that changed — the content and focus evolved just as much. When we launched the inventory in 2009, the Flemish Institute for Immovable Heritage had just been founded as a scientific institution that, for the first time, brought together research into archaeology, built heritage and landscapes. Several inventories and information systems (databases, but also books like Bouwen door de Eeuwen Heen) came under shared management for the first time. Since those systems each had their own angle, the first version of the Flanders Heritage Inventory was conceived as a portal: one look and feel, but each inventory kept its own data model. At launch in May 2009, the portal held the built-heritage inventory and the WWI heritage inventory, plus supporting modules for images, events and thesaurus terms.

Between 2009 and 2015, new modules were added: organs, archaeological zones, historic gardens and parks, heritage trees and woody plantings, landscape anchor points, and maritime heritage. It quickly became clear that despite methodological differences (a building gets demolished, a tree gets felled), these inventories were essentially doing the same thing: describing what heritage exists where, documented with images, descriptions and thesaurus terms. Every new module was therefore built as an adapted version of the built-heritage inventory, the main remaining difference being the location component: precise address data for small elements versus larger heritage ensembles for the other modules.

When VIOE merged with the Ruimte en Erfgoed agency in 2012, the protected-heritage database came along with it. It turned out to hold mostly legal data and little content, so it was folded into the inventory as a separate module that largely shared the same data model. This eventually became the designation objects dataset (see Heritage objects and designation objects), made public in June 2016.

As the inventory evolved, it became clear that all these different inventories weren't actually that different, and we started treating them more as one integrated inventory — which also led to more communication and collaboration between heritage researchers. Alongside the launch of designation objects, we also introduced the term "heritage objects": every object from the scientific inventories got its own heritage object with a unique URI. In 2016 this was still largely cosmetic — the various detail pages were merged into one, but underneath they remained separate datasets with their own data model. At that point it became clear the old inventory had been pushed as far as it could go within its original design.

So preparations began for what eventually became the new inventory — partly because our view of the scientific inventories had shifted, from separate silos to one large inventory of heritage objects, and partly because the underlying technology was due for replacement. Now that the new inventory is here, we keep refining it until it does everything we want within its current capabilities.

Want to know more about the inventory? A few other posts worth reading:

• General information about the new inventory
• Heritage objects and designation objects: what are they and why do they exist?
• Themes, people and events: what are the three supporting modules for?
• From searching to finding on the new inventory: how are the search options structured?
• Full-text search in the inventory: how does full-text search work, illustrated with heritage objects?

The IT world keeps evolving fast. Our core business may be the past, but we want to manage that past in a forward-looking way — with a continuous, adaptive approach that stays open to new insight, both into our own subject matter and into the technology we use to manage and share it. Questions about any of this are always welcome — get in touch.

Full-text search works like a major web search engine: you're after a fairly specific object or document, and the search engine tries to put the best match on top. Search for Gravensteen and you get the most "Gravensteen-like" object first.

Several factors determine what counts as most relevant: the more often your search term appears in an object, the more relevant; the smaller the field it appears in, the more relevant; and the more often the term appears across all objects overall, the less relevant. Certain fields also weigh more heavily than others — a title counts for more than the body text of a record. Search for Gravensteen and an object titled that way outranks one where the term appears once in the text.

Type Gravensteen into the Algemeen ("general") field of the heritage objects search form and you get https://inventaris.onroerenderfgoed.be/erfgoedobjecten?tekst=gravensteen, with the Gravensteen in Ghent on top. Case doesn't matter here.

Want to know specifically about the Gravensteen in Aalst? Search Gravensteen Aalst and you get only 2 results: objects containing both Gravensteen and Aalst. By default, each word is treated as a separate term combined with AND — written as +, so Gravensteen Aalst equals Gravensteen+Aalst. Prefer either one or the other? Use the OR operator, the pipe character |: Gravensteen|Aalst. The third operator is NOT, a - sign: Gravensteen -Aalst gives you everything with Gravensteen but not Aalst.

By default the search engine splits your query on spaces. Search Grote Markt Aalst and you get quite a few results, including, right at the bottom, Paviljoen De Notelaer — the words grote, markt and aalst do appear, just not next to each other. To search for the exact phrase, use quotes: "Grote Markt" Aalst searches for two terms instead of three, and returns fewer, more relevant results.

For more complex combinations, use parentheses to control operator precedence. Search vismarkt brugge gent and you get objects containing all three terms — not what you meant. vismarkt + brugge | gent then returns far too many results, because operators have a fixed precedence. The fix: group with parentheses, vismarkt + (brugge|gent), to find records about the fish market that also mention Bruges or Ghent.

You can also search on part of a word with a postfix wildcard: gedenk* matches gedenksteen, gedenkplaat and similar words. This only works at the end of a term — *linde won't match herdenkingslinde. You can combine all of this: visgraat* (oost-vlaanderen|west-vlaanderen) -brugge finds objects with a word starting with visgraat, in East or West Flanders, but not in Bruges.

Which fields are actually searched in full text, and in what order of importance? The text, the text's title, the short description (shown in a search result), province, municipality, sub-municipality and street names, thesaurus terms, and the object's own name. We show every object containing your term, unless there are more than 10,000 (the maximum number of results).

In short, these are the operators you can use:

• Multiple terms are implicitly combined with AND; make it explicit with +
• Combine with OR using |
• Exclude a term with NOT using -
• Turn multiple words into one term with quotes "
• Control operator precedence with parentheses ()
• Search by prefix with a postfix wildcard *

Happy searching! Questions about search are always welcome — get in touch.

Heritage objects are the beating heart of the inventory: the things we and you consider heritage, from Antwerp Cathedral or the Gravensteen to the Zwin nature reserve, a chapel, a tree, a ship or an organ. The focus isn't on legal consequences but on the scientific record: what is it, how big, where, how old, what does it look like, who was involved, where can I learn more? A heritage object's boundary is often a bit fuzzy in practice — for the Gravensteen, one person might see only the keep, another might include the moat, and a third might count the adjoining square as well. We settle on one boundary per object without treating it as perfectly exact.

Designation objects, by contrast, are heritage as it's legally anchored: the protection or listing of a heritage object. Where a heritage object's boundary can be a bit vague, a designation object's must be beyond dispute, since it determines which legal consequences apply to a given piece of Flanders. Since the new Immovable Heritage Decree, we now delineate listed heritage with a polygon rather than points. The key questions for a designation object: exactly how large is it, what type of designation is it, why does it have heritage value, and which decree or document backs that decision? A single heritage object can be anchored more than once, under different statuses.

Antwerp Cathedral, a heritage object and its designations

Look at Antwerp Cathedral, for instance, and you'll find four designations: a listing as built heritage, a designation as UNESCO World Heritage, a protection as a monument, and an additional protection of a section of wall, also as a monument. The heritage object "the cathedral" tells you what it is; the designation objects tell you, in detail, what applies to its various parts.

Couldn't this be simpler?​

At first glance, this split looks complex and arbitrary. It emerged during the protection-database project, shortly after the merger of the Ruimte en Erfgoed agency and the Flemish Institute for Immovable Heritage. The first managed the protection database, the second the inventory database, which at the time consisted of several separate inventories (built heritage, gardens and parks, woody plantings, ...), each with its own record per element.

Because the protection database offered far less functionality than the inventory database at the time, all protected heritage was added into the inventory database, immediately equipped with images, thesaurus terms and extended descriptions. In that first data model, protected heritage was described identically to inventoried heritage: a record for a church in the built-heritage inventory, a separate record for that same church as a protected monument, and possibly yet another record as part of a village townscape. Those records largely repeated the same content, sometimes with slight differences due to a different boundary — a nightmare to maintain whenever new insight about a building came to light.

A similar problem existed between the different inventories themselves. When they were still published on paper (in series like M&L Cahiers and Bouwen door de Eeuwen Heen), overlap between, say, a historic garden and its associated built heritage was manageable; online, this proved less straightforward, sometimes leading to contradictory records.

Eventually we changed course by strictly separating two things. On one hand, the content: we now assign every heritage object one or more disciplines (archaeological, architectural, landscape, or maritime), and bring as much information as possible together into a single record, regardless of which part of it is protected. On the other hand, the legal information, which we want to be able to handle independently — a protection can cease to exist, for example, without the heritage itself disappearing. That's how we reworked the protection database into a database of designation objects, a term we borrowed from Historic England, where "designation" refers to the formal act of attaching legal consequences to heritage.

Everything is connected​

Our heritage is vast and varied, and every record puts just a small piece of reality in the spotlight — pieces that are connected to each other. That's why we've been linking objects with relations for about a decade. Where heritage used to be managed mostly as isolated points, there's been a long-running shift toward larger wholes and contexts that matter just as much as the small elements we readily recognise as heritage. Former built ensembles, archaeological zones and anchor points have all become heritage objects, with a consistent distinction between ensembles (larger areas) and elements (smaller-scale pieces of heritage). Since 2009, we've linked heritage objects using three relations:

• is related to: a connection between two objects, without one containing the other — for example a coal mine and a miners' housing estate.
• contains: one heritage object contains another, such as a castle estate containing the coach house, or a church containing a separately described organ.
• is part of: the inverse of "contains" — the organ is part of the church, the coach house part of the estate.

For the interaction between heritage objects and designation objects, we distinguish three relations:

• is designated as: the heritage object and the designation object are (nearly) identical in extent — the heritage object is (roughly) fully protected or listed.
• encompasses the designation as: the heritage object is larger than the designation object, e.g. a church of which only the tower is protected.
• is part of the designation as: the heritage object is smaller than the designation object, e.g. an individual tree within a protected landscape.

Help, I'm looking for something!​

So when do you use which dataset? You can search heritage objects or search designation objects, and both forms offer filters related to legal consequences. With heritage objects, you're primarily searching on content characteristics — the unit of information is heritage. With designation objects, you're searching on characteristics of the designation itself — the unit of information is a legal decision about heritage.

Search for protected libraries, for example, and typologie=bibliotheken + rechtsgevolgen=beschermd on heritage objects gives 17 results, while typologie=bibliotheken + categorie=beschermingen + geldig=true on designation objects gives 22 results — not quite the same thing. The first is 17 heritage objects that are (partly) a library and carry a protection; the second is 22 protected objects that relate to a library in some way. The Loppem Castle estate, for instance, is protected twice: the whole estate as a landscape, and the manor house with outbuildings separately as a monument.

Splitting our information into heritage objects and designation objects lets us handle content flexibly and make additions without touching the legally anchored data. Got suggestions for making our information clearer? Get in touch.

The inventory currently holds five major datasets: heritage objects (erfgoedobjecten), designation objects (aanduidingsobjecten), people, themes and events. Many search options and principles are shared across these datasets — searching for heritage or designation objects in a given municipality works identically, and so does searching by thesaurus term.

User interface vs. REST service​

When it comes to search, we distinguish between the search service itself and the UI that uses it. Search is complex: multiple parameters, boolean combinations (this AND that, this OR that, NOT this), searching by id or by text, wildcards — and it all has to stay simple and unambiguous. In practice, the perfect search UI doesn't exist; it always depends on the user, which is hard to predict. That's why our search services often support more than what the standard UI exposes: we build the UI for the average user, while the service itself targets developers and experienced users.

By "UI" we mean the search forms themselves, such as https://inventaris.onroerenderfgoed.be/erfgoedobjecten/zoeken, where you enter search parameters in a guided way (with suggestion lists for municipality and street names, for instance). The downside: a UI is expensive to build, and complex queries don't always fit neatly into one.

The user interface makes simple searches easy

The service itself is a machine-queryable REST service that uses JSON to exchange information. A search result on the new inventory can be browsed as HTML or downloaded as JSON or CSV — just request the same URL with a different Accept header, such as application/json. You can do this with a command-line tool like curl, a REST client, or your favourite programming language:

$ curl -X GET -H "Accept: application/json" https://inventaris.onroerenderfgoed.be/erfgoedobjecten?gemeente=278

Full-text search vs. filtering​

The search forms support both full-text search (often just called "search") and filtering. These sound similar but serve very different purposes — though both help you avoid seeing irrelevant data.

Filtering is black and white: an object either matches a criterion or it doesn't. You might want all heritage in a municipality or street, or all churches, or all churches in a given municipality — often you're not after one specific object, sometimes you just want a count.

Full-text search is a shade of grey: the search engine tries to give you the most relevant result. Search for Gravensteen or Sint-Veerle and you're usually after a small number of objects, wanting the most relevant one at the top — the same way major web search engines like Google work.

You can of course combine the two. A full-text search for Gravensteen returns ten objects, with the Gravensteen in Ghent on top — the last result is the archaeological zone of Aalst, because "gravensteen" also appears in its description. Add a filter for the municipality of Ghent, and you're left with seven results, still topped by the Gravensteen.

As long as you run a full-text search via the Algemeen ("general") field, the application sorts by relevance by default; without full-text search, it sorts by location. When full-text searching, you can still change the sort order, though that's rarely useful.

In a follow-up post we explain how to search full-text more precisely (Full-text search in the inventory), and exactly how we determine which record is most relevant for a given query.

Setting up a demo instance used to take some manual work. We now publish a Docker image that bundles both a demo application and its companion Linked Data Fragments server, so you can get a working instance running in minutes.

After installing Docker (the CE edition is more than enough), pull and run the image:

$ sudo docker pull atramhasis/demo
$ sudo docker run -p 6543:6543 -p 3000:3000 atramhasis/demo

The demo app is then available at http://localhost:6543, and the bundled Linked Data Fragments server at http://localhost:3000.

You can also pin a specific version (from Atramhasis 0.6.4 onward):

$ sudo docker pull atramhasis/demo:0.6.4
$ sudo docker run -p 6543:6543 -p 3000:3000 atramhasis/demo:0.6.4

Keep in mind this is meant for a quick first look, not long-term use: any edits you make are discarded when the container stops. If you need persistence while still using Docker, customise the Dockerfile to fit your needs.

Static map generator​

Generating this kind of map is done with the static map generator, a module built for Flanders Heritage Agency together with external partners. Its purpose: assemble static maps from a mix of geographic formats (such as GeoJSON), a background layer (such as WMS), and layout overlays like text and a scale bar. Based on a configuration file, the generator merges all layers into one image with a scale bar, returned either as an image file or as base64.

The generator works both as a Python module and as a REST service, so it's easy to plug into your own project — use the library directly if you work in Python, or run it as a standalone application on a server if you don't.

A municipality's heritage atlas​

The inventory is a great tool for learning about our heritage, but sometimes a local copy is handy — say, to take on the road without an internet connection. Combining a few of our services lets you build your own heritage atlas.

As an example, we use the municipality of Edegem. First, all heritage objects and designation objects within the municipality are fetched via the geo search services. Then a base configuration is set up for the image: background layer, text, width and height. Each object's geometry is added as a separate layer, and finally the configuration is handed to the static map generator, which returns the image. Edegem's own boundary comes from a GeoJSON file based on data from Informatie Vlaanderen. The full script is on GitHub.

That gets you a map of all the heritage we know about in Edegem:

Zooming in on individual objects​

You can also generate a separate map for each heritage object — for example with a different background layer, and the object's name printed on the map. That gives you one map per object from the inventory, ready to print or process further. As always, both our data and that of Informatie Vlaanderen are open data, free to reuse.

Fort 5

Hazeschranshoeven

Kasteel Hof ter Linden

Garden City Elsdonk

Want to try the map generator yourself? Check out the static map generator on GitHub, or browse the live API docs at https://geo.onroerenderfgoed.be/zoekdiensten/api_doc.

Our colleagues at Historic England define a thesaurus as a structured wordlist used to standardize terminology, used to assist in indexing and retrieving information within databases that make use of the same terminology. Structuring related terms like this opens up a few useful things.

First, it lets you express equivalence. Rather than saying two terms are "synonyms," we say both are verbal expressions of the same underlying concept — so instead of stating Jugendstil equals Art Nouveau, we say there's a single concept for that artistic style, labelled with both terms. Subtle difference, but it changes how you interact with the thesaurus.

Second, there are hierarchical relations: one term broader than another, the other narrower. A cathedral is a church, a church is a religious building, so a cathedral is a religious building too. Not all hierarchical relations are strictly "is a" — "is part of" and "is an instance of" exist as well, and they complicate matters. See On the composition of ISO 25964 hierarchical relations (BTG, BTP, BTI) for how they interact.

Third, the associative relationship — the "softest" one, just stating two terms or concepts are related. Coal mine relates to miner's houses because in Flanders, every coal mine had its own little town where the miners lived.

Thesauri also let you attach a scope note: a written definition of a concept and how it should be used. This turns out to matter a lot in practice — asking experts to define concepts they assumed were self-evident has caused more than one heated discussion. Without a definition, everyone uses a concept however they like, ignoring that others might disagree.

So thesauri help us reach consensus on what concepts mean and share that with the outside world (which is why we publish them as open data). But we also have a very practical reason to build and maintain them: indexing. When someone searches for fountains in our inventory system, the thesaurus is consulted. If fountains isn't a known term, nothing gets indexed under it and the search stops there. If it is, the system also checks for narrower terms — in this case water tricks is a defined narrower type of fountain — so a search for fountains returns records indexed as either fountains or water tricks.

Those water tricks also show off another handy feature. Look at the record for water tricks and you'll see we call them bedriegertjes in Dutch but never got around to an English label. Luckily, we've linked our bedriegertjes concept to the same concept in the Art & Architecture Thesaurus, which tells us the English terms are water tricks or joke fountains — and even gives us the German and Spanish equivalents. That opens up a lot of possible interactions with other systems.

In the end, thesauri are a means, not an end — our job is managing heritage, not building thesauri. But they help enormously in defining what that heritage is, searching through it, and linking it from our local level to the transnational one. If you want more detail on how we built ours, including some do's and don'ts, the original post pointed to a bibliography entry (Mortier et al., 2017) that we weren't able to carry over exactly.

An example is worth a thousand words. Say we want all heritage within a hundred metres of a point in Flanders:

$ curl -X GET --header 'Accept: application/json' 'https://geo.onroerenderfgoed.be/zoekdiensten/afbakeningen?categorie=aanduidingsobjecten&geometrie=%7B%22type%22%3A%20%22Point%22%2C%20%22coordinates%22%3A%20%5B4.7676665601685%2C50.985228897907%5D%7D&buffer=100'

That returns a list of results, each a JSON object with the attributes id, uri, categorie, type, naam and geometrie. naam is a short description. The id uniquely identifies the object within its source dataset; the uri is guaranteed unique across all datasets — a global identifier that's really just a link to more information. Request https://inventaris.onroerenderfgoed.be/erfgoedobjecten/134454 in a browser, for instance, and you land on a page about that object in the Inventaris Onroerend Erfgoed. Prefer the raw JSON? Send an Accept: application/json header:

$ curl -L -X GET --header 'Accept: application/json' 'https://id.erfgoed.net/erfgoedobjecten/134454'

In this example we've found a heritage object from the scientific inventory of gardens and parks — you can tell from the type attribute, an object with a uri and a label. That uri points to a term in a thesaurus of inventaristypes or aanduidingstypes; follow it for more detail, such as the fact this inventory is sometimes internally called ile_park.

The geometry itself comes back as GeoJSON, and since it can get large and isn't always needed, you can tell the service to leave it out:

$ curl -X GET https://geo.onroerenderfgoed.be/zoekdiensten/afbakeningen?&buffer=100&geef_geometrie=0

By default the service searches across all kinds of objects, but you can filter with the categorie parameter:

• Erfgoedobjecten ("heritage objects"): the content-focused objects that make up our heritage — the scientific inventories.
• Aanduidingsobjecten ("designation objects"): the legal anchoring of heritage objects, both protected and listed (which you can tell from the type's URI), including heritage landscapes and Unesco core and buffer zones.
• Plannen ("plans"): currently just management plans, to be extended later with heritage master plans.

To see only designated objects, for example:

$ curl -X GET https://geo.onroerenderfgoed.be/zoekdiensten/afbakeningen?&buffer=100&geef_geometrie=0&categorie=aanduidingsobjecten

For simple questions like "give me all heritage around a point," the above works fine. You're not limited to points either — (multi-)polygons and lines work too, though embedding a full GeoJSON geometry in the URL gets unwieldy fast. That's why the service also supports a POST request, letting you put the query in the request body instead.

The service is freely accessible and reuse is encouraged. For a quick overview of what it can do, we recommend the live API docs at https://geo.onroerenderfgoed.be/zoekdiensten/api_doc.

We hope this fairly simple webservice proves as useful to you as it is to us. Comments, questions or further needs are always welcome at ict@onroerenderfgoed.be.

As a person, you have a few options. Head to our Geoportal and zoom in on a location to see, in a couple of clicks, what heritage is present there. If maps aren't your thing, our Inventory lets you search for all heritage in a given street or municipality through a search form — less precise, perhaps, but a quick way into the history and architecture of your neighbourhood.

All geographic information about immovable heritage can be found at https://geo.onroerenderfgoed.be

If you'd rather work with the data yourself, our heritage inventories and our protected and listed heritage sites can be downloaded as GIS files, each geometry carrying a URL to more information. Handy offline, but regenerated every night — so a day-old download is already stale. If you need the current state at all times, our OGC webservices via our Geoserver always reflect the latest data, unlike the downloads.

Finally, if you're technically inclined and want to use our data directly in your own systems, there's Geozoekdiensten ("geo search services"). Right now this is a single webservice built to answer exactly one question: what's located in this area? You send it a geometry, and it tells you which heritage lies wholly or partly within it — a simple JSON structure with an id, a uri, a type and the full geometrie for each object. We've been using this service internally for a while, and are now happy to share it.

In a follow-up post (Geozoekdiensten: what's here?) we explain exactly how to use this service.