# Reconciliation Service Extractor (OpenRefine / W3C) (`datamule/reconciliation-service-extractor`) Actor

Point at ANY W3C Reconciliation (OpenRefine) service and pull results: fetch the capability manifest, batch-match query strings to candidate entities with scores, autocomplete (suggest), and fetch property values (extend). Works with Wikidata, GND, Getty and any conforming endpoint.

- **URL**: https://apify.com/datamule/reconciliation-service-extractor.md
- **Developed by:** [Datamule](https://apify.com/datamule) (community)
- **Categories:** Developer tools, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.35 / 1,000 records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Reconciliation Service Extractor (OpenRefine / W3C)

Point this actor at **any W3C Reconciliation Service API endpoint** (the OpenRefine
reconciliation standard) and pull structured results — no per-service code required. It works
with Wikidata, the German National Library (GND / lobid), the Getty Vocabularies, and every
other conforming reconciliation endpoint.

Reconciliation is how you turn messy text — a list of person names, place names, organizations,
subject terms — into **linked, canonical identifiers** from an authority (a Wikidata Q-id, a GND
number, a Getty ULAN/AAT/TGN id). It's the backbone of data cleaning, entity linking, and
knowledge-graph building in libraries, museums, archives, and open-data projects.

### What it does

Four modes, auto-gated on what the target service actually advertises in its manifest:

| Mode | What it returns |
|------|-----------------|
| **manifest** | The service capability manifest — name, identifier space, default types, and which optional modes (suggest/extend/preview) the service supports. The cheap connectivity probe; always run first. |
| **reconcile** | Batch-match a list of query strings to candidate entities. One row per candidate, carrying the raw `score`, the `match` auto-match flag, the entity `type[]`, and `description`. |
| **suggest** | Autocomplete entities, properties, or types from a text prefix (only if the service advertises a suggest endpoint). |
| **extend** | Data-extension — fetch property values for a set of matched ids (e.g. birth date + birth place for a person id). Only if the service advertises extend. |

### Example input

```json
{
  "endpoint": "https://wikidata.reconci.link/en/api",
  "modes": ["manifest", "reconcile", "extend"],
  "queries": ["Albert Einstein", "Marie Curie", "Isaac Newton"],
  "typeFilter": "Q5",
  "limit": 5,
  "extendIds": ["Q937"],
  "extendProperties": ["P569", "P19"]
}
```

### Endpoints you can point it at

- **Wikidata** — `https://wikidata.reconci.link/en/api` (general knowledge graph; supports all four modes)
- **GND (German National Library)** — `https://lobid.org/gnd/reconcile` (library authority data)
- **Getty Vocabularies** — `https://services.getty.edu/vocab/reconcile/` (art & architecture: ULAN, AAT, TGN)
- ...and any other endpoint conforming to the [Reconciliation Service API spec](https://reconciliation-api.github.io/specs/latest/).

### Output

Each result is one flat row tagged with its `mode`. Reconcile rows carry the query, the matched
`id`/`matchName`, the raw `score` (scales differ per service — kept un-normalized), the
`match` flag, and the entity `type[]`. Manifest rows carry the full capability description.
Results render as a clean table in the Apify Console and export to JSON, CSV, Excel, and more.

### Notes

- Scores are **not normalized** — different services use different scales (0–100, unbounded
  float), so the raw score is preserved for honest cross-service comparison within one service.
- A query with zero candidate matches is a real, honest empty result (emitted as a no-match row),
  not an error.
- Optional modes are skipped with a warning if the target service does not advertise them.

### Pricing

Pay-per-event: you are charged per result row produced. Fetch a manifest, reconcile a list, or
extend a set of ids — you only pay for the records you get back.

# Actor input Schema

## `endpoint` (type: `string`):

The base URL of ANY W3C Reconciliation Service API (the OpenRefine reconciliation spec). Fetching this URL returns the service manifest. Examples: https://wikidata.reconci.link/en/api , https://lobid.org/gnd/reconcile , https://services.getty.edu/vocab/reconcile/

## `modes` (type: `array`):

Which operations to run. 'manifest' fetches the service capability manifest (cheap connectivity probe). 'reconcile' batch-matches your query strings to candidate entities. 'suggest' autocompletes (only if the service advertises it). 'extend' fetches property values for ids (only if advertised).

## `queries` (type: `array`):

For 'reconcile' mode: the list of strings to match against the service (person names, place names, subject terms, etc). Each query yields one row per candidate match.

## `typeFilter` (type: `string`):

Optional entity type id to constrain reconcile candidates (e.g. a Wikidata Q-id like Q5 for humans, or a service-specific type from the manifest's defaultTypes). Leave blank to search all types.

## `limit` (type: `integer`):

Maximum candidate matches to return per query (and per suggest call). Leave blank for the service default.

## `suggestFlavour` (type: `string`):

For 'suggest' mode: what to autocomplete.

## `suggestPrefix` (type: `string`):

For 'suggest' mode: the text prefix to autocomplete (e.g. 'Einst').

## `extendIds` (type: `array`):

For 'extend' mode: the entity ids whose property values you want (e.g. \['Q937']). Get these from a prior reconcile run.

## `extendProperties` (type: `array`):

For 'extend' mode: the property ids to fetch for each entity (e.g. \['P569','P19'] on Wikidata for birth date / birth place).

## Actor input object example

```json
{
  "endpoint": "https://wikidata.reconci.link/en/api",
  "modes": [
    "manifest",
    "reconcile"
  ],
  "queries": [
    "Albert Einstein",
    "Marie Curie",
    "Isaac Newton"
  ],
  "limit": 5,
  "suggestFlavour": "entity"
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "endpoint": "https://wikidata.reconci.link/en/api",
    "queries": [
        "Albert Einstein",
        "Marie Curie",
        "Isaac Newton"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("datamule/reconciliation-service-extractor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "endpoint": "https://wikidata.reconci.link/en/api",
    "queries": [
        "Albert Einstein",
        "Marie Curie",
        "Isaac Newton",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("datamule/reconciliation-service-extractor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "endpoint": "https://wikidata.reconci.link/en/api",
  "queries": [
    "Albert Einstein",
    "Marie Curie",
    "Isaac Newton"
  ]
}' |
apify call datamule/reconciliation-service-extractor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=datamule/reconciliation-service-extractor",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/OYGWkmyvBPhlxznOw/builds/VHlIwnnOjBf6YUcBh/openapi.json