Reconciliation API

Use the Reconciliation Service API to match and reconcile textual strings in your data with terms.

The Network of Terms implements version 0.2 of the Reconciliation Service API (W3C Entity Reconciliation Community Group Final Report, 10 April 2023). Version 1.0 of the specification is still a draft and is not yet supported.

If you want to use the Reconciliation Service API, configure one or more service endpoints in your OpenRefine application. An endpoint’s URL is structured like https://termennetwerk-api.netwerkdigitaalerfgoed.nl/reconcile/{sourceUri}. A full list of endpoints can be found on the Network of Terms website, or discovered programmatically via the GraphQL API – see Discover reconciliation endpoints.

Note that the Network of Terms provides Reconciliation endpoints only for terminology sources that do not offer such endpoints themselves.

Using the API from OpenRefine

In OpenRefine, open the column you want to reconcile and choose Reconcile → Start reconciling…. The first time you use a Network of Terms endpoint, click Add standard service… and paste the endpoint URL for the source (for example https://termennetwerk-api.netwerkdigitaalerfgoed.nl/reconcile/https://data.cultureelerfgoed.nl/term/id/cht). OpenRefine remembers the service for subsequent projects.

In the reconciliation dialog, select Reconcile against no particular type. Network of Terms endpoints don’t advertise a default type for their candidates, and leaving the default option (“Reconcile against the suggested type”) selected makes OpenRefine match every cell against an empty type set, so no candidates come back. Picking “no particular type” lets the source’s own search query decide what counts as a match.

Adding columns from reconciled terms

Once a column is reconciled, choose Edit column → Add columns from reconciled values… to fetch more of what the source states about each term. The data-extension endpoint offers these properties and returns the ones you select, each empty where the source states nothing:

Property	Values
prefLabels, altLabels, scopeNotes	Labels and notes, in the selected language
birthDates, deathDates	Dates of a person, as EDTF strings
birthPlaces, deathPlaces, genders	Names, or IRIs where the source names nothing
broaderTerms, narrowerTerms, relatedTerms	Terms in the same source, as reconciled entities named by their preferred label; IRIs where the source gives no label
exactMatches	IRIs of the same term in other sources, such as ULAN, VIAF or Wikidata

Language selection

Reconciliation endpoints honor the standard Accept-Language HTTP header for content negotiation. Clients send a ranked list of preferences (e.g. en, nl;q=0.8); the server picks a single best match. Currently honored values are nl and en; the default and fallback when nothing matches is nl.

The header controls:

• name and description of every candidate returned by /reconcile/{sourceUri}
• Values returned by the data-extension endpoint /extend (and /reconcile/{sourceUri}/extend)
• The HTML preview at /preview/*
• Service manifest labels (column titles, suggest service titles, etc.)

The v0.2 specification does not define a per-query language field; the HTTP header is the only knob. The v1.0 draft introduces a per-query lang field – when that specification stabilizes and OpenRefine adopts it, we will revisit support for it here.

Example

A minimal reconciliation query against the Cultuurhistorische Thesaurus (CHT), asking for English candidate labels:

curl -X POST \
  -H 'Accept-Language: en' \
  -d 'queries={"q0":{"query":"fiets"}}' \
  https://termennetwerk-api.netwerkdigitaalerfgoed.nl/reconcile/https://data.cultureelerfgoed.nl/term/id/cht

The response is a JSON object keyed by the query identifier (q0), with each candidate’s name and description returned in English where available, falling back to whatever the source provides otherwise.