Skip to main content

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.

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.