MetaMuseum
Menu
← Documentation home

Canonical Markdown source · Oct 20, 2018

Reconciliation Service (C2)

ops/reconciliation-service.md · 84 lines · SHA-256 05162c313ea9

This runbook covers the C2 FastAPI reconciliation service with Redis URI cache.

Service path:

  • `services/reconciliation-service/`

What it does:

  • Exposes `POST /reconcile/lookup` for authority lookups across:
  • Getty SPARQL
  • VIAF AutoSuggest
  • Wikidata entity search
  • GeoNames search
  • Caches upstream URI responses in Redis using deterministic SHA-256 cache keys.
  • Returns per-provider cache hit/miss metrics so cache behavior is observable.
  • Runs B6.1 exhibition/literature reconciliation as first-class service pipelines.

Install deps


pnpm reconcile:service:deps

Run locally


pnpm reconcile:service

Default bind:

  • `http://127.0.0.1:8002`

Health check


curl http://127.0.0.1:8002/health

Example lookup


curl -X POST http://127.0.0.1:8002/reconcile/lookup \
  -H "content-type: application/json" \
  -d "{\"query\":\"vincent van gogh\",\"providers\":[\"wikidata\",\"viaf\"],\"limit\":5}"

B6.1 pipeline endpoints

List available pipelines:


curl http://127.0.0.1:8002/reconcile/pipelines

Run exhibition/literature reconciliation pipeline:


curl -X POST http://127.0.0.1:8002/reconcile/pipelines/exhibitions-literature \
  -H "content-type: application/json" \
  -d '{"records":[{"id":"https://example.org/exh/1","type":"PropositionalObject","_label":"Sample Exhibition","_source":{"provider":"met"}},{"id":"https://example.org/exh/2","type":"Activity","_label":"Sample Exhibition","classified_as":[{"type":"Type","_label":"Exhibition"}],"_source":{"provider":"rijks"}}]}'

Threshold band metadata:


curl http://127.0.0.1:8002/reconcile/pipelines/exhibitions-literature/bands

Environment variables

  • `RECONCILIATION_REDIS_URL` (default `redis://127.0.0.1:6379/0`)
  • `RECONCILIATION_CACHE_KEY_PREFIX` (default `mm:reconcile:uri`)
  • `RECONCILIATION_CACHE_TTL_SECONDS` (default `86400`)
  • `RECONCILIATION_HTTP_TIMEOUT_SECONDS` (default `15`)
  • `RECONCILIATION_MAX_RESULTS_DEFAULT` (default `5`)
  • `GETTY_SPARQL_ENDPOINT` (default `https://data.getty.edu/museum/collection/sparql`)
  • `VIAF_AUTOSUGGEST_ENDPOINT` (default `https://viaf.org/viaf/AutoSuggest`)
  • `WIKIDATA_API_ENDPOINT` (default `https://www.wikidata.org/w/api.php`)
  • `GEONAMES_SEARCH_ENDPOINT` (default `http://api.geonames.org/searchJSON`)
  • `GEONAMES_USERNAME` (required to query GeoNames)