# Sports Team and Player Identity Candidate Matcher (`zinin/sports-team-player-identity-matcher`) Actor

Resolve team and player names to Wikidata candidates with sport, country and type evidence. Preserve ambiguity, entity revisions and source provenance.

- **URL**: https://apify.com/zinin/sports-team-player-identity-matcher.md
- **Developed by:** [Tim Zinin](https://apify.com/zinin) (community)
- **Categories:** Games
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.55 / 1,000 useful identity candidate report delivereds

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Sports Team and Player Identity Candidate Matcher

Reconcile team and player names from different sports datasets with Wikidata candidate IDs, labels and structured evidence. The Actor keeps ambiguous results visible so you can review main clubs, reserve teams, women's teams and similarly named people or works before merging your records.

This independent tool returns candidates, not verified identities. It does not predict sporting outcomes or infer a complete sports taxonomy from names or descriptions.

### Input

```json
{
  "queries": [
    {"sourceId": "team-home", "name": "Bayern Munich", "sportQid": "Q2736"},
    {"sourceId": "player-1", "qid": "Q1426", "name": "Roger Federer", "sportQid": "Q847"}
  ],
  "candidateLimit": 3
}
```

Supply 1–10 queries. Each needs a unique `sourceId` from your dataset and a `name` or exact Wikidata `qid`. With a QID, the Actor reads that entity directly; an accompanying name is checked against its labels and aliases. Resolving a supplied ID does not prove it is the correct identity for your record.

Without a QID, English search examines the first `candidateLimit` results: 3 by default, at most 5. The limited search can miss relevant entities. Candidate order follows the source and is not a confidence score. A single candidate is still unverified.

Optional exact claim constraints:

| Input | Wikidata evidence |
|---|---|
| `sportQid` | Sport, P641; for example Q2736 association football or Q847 tennis |
| `countryQid` | Country, P17 |
| `nationalityQid` | Country of citizenship, P27; distinct from P17 |
| `typeQid` | Instance of, P31; exact listed class only |

The Actor reports whether the requested QID is present in nondeprecated claims, absent from the observed values, or not stated. It does not follow subclass hierarchies or interpret temporal qualifiers. These claims do not prove current membership or eligibility. `qualifyingCandidateQids` lists candidates with all supplied constraints observed; when no constraints are supplied, it lists all returned candidates. It never automatically merges your IDs.

For example, a search for Bayern Munich can also return a film with an exact name agreement but no sport claim. The report retains it and marks the missing evidence rather than treating a matching title as proof of a football club.

### Output and source

Each `identity_candidate_report` links your `sourceId` to examined QIDs, candidate labels and aliases, English descriptions when available, revision IDs, exact claim evidence, name agreement and constraint states. Labels and aliases retain their source language: English (`en`) or multilingual (`mul`). Name agreement uses NFKC normalization, whitespace normalization and lowercase; it is not an identity confidence estimate.

All real reports include source URLs, retrieval timestamps, SHA-256 hashes of decoded response bytes, and Wikidata/CC0 attribution. No portraits, logos, contact fields, sitelinks or unrelated raw claims are exported. Missing or redirected QIDs are reported without following redirects. An empty examined result does not establish global nonexistence.

Data comes from the public [Wikidata Action API](https://www.wikidata.org/wiki/Wikidata:Data_access), using item search followed by a bounded entity request. Requests are sequential, at least one second apart per run, with a 20-second deadline and 2 MiB decoded body limit each. The Actor uses `maxlag=5`, an identifying User-Agent and compressed responses. HTTP errors, rate limits and maxlag errors stop collection without automatic retries. Separate concurrent runs have independent request clocks.

Structured data is available under [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/). Charges are for this Actor's processing and delivery. Report incorrect source facts through the entity's Wikidata page; report Actor defects through its Apify Issues page.

### Pricing and partial runs

One delivered query report containing at least one resolved candidate requests one `result-found` event. This includes ambiguous candidates or candidates that do not meet your optional constraints: the report supplies the examined evidence. Repeated queries and snapshots are billable again. Empty reports, diagnostics and synthetic demos request no result event. A configured start charge may apply; check current Apify pricing and set Max total charge.

The budget guard checks that another paid report fits before querying the source. If it does not, collection stops, including queries that might otherwise have returned an unbilled empty result. A later source failure leaves earlier delivered reports in the Dataset; inspect `sourceId` and rerun only the unresolved portion if appropriate. A run with no candidates can succeed but does not establish matching quality or global absence.

`OUTPUT` contains counts, source snapshots and completion flags without duplicating candidate evidence. Dataset `billing.resultEventRequested` and `settlement: "unconfirmed_at_write"` describe the intent at write time and are not updated after acknowledgement. Use the run's actual charged-event counters and, when available, `OUTPUT.confirmedResultEvents` to confirm billing.

Unknown writes or charge acknowledgements are never automatically retried. `OUTPUT` may be missing after a timeout, termination or uncertain storage write; its absence does not imply no data or charges. Check the Dataset and run counters before repeating a run.

### Synthetic demo

```json
{"demo": true}
```

Demo ignores the known `queries` and `candidateLimit` fields, including form defaults. It makes no source requests and requests no result event. The synthetic row uses the same report type but has `isDemo: true`, `status: demo`, `source: null` and no real QID. Exclude demo rows when importing real data. Its summary has `outcome: demo` and `collectionComplete: false` because it does not collect a source.

# Actor input Schema

## `demo` (type: `boolean`):

Invented report; ignores queries and candidateLimit. No source requests or result events. A configured start charge may apply.

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

Required for real collection. Each unique sourceId needs a name or exact QID. Optional exact constraints: sportQid=P641, countryQid=P17, nationalityQid=P27, typeQid=P31. Missing claims remain unknown; no class-hierarchy inference.

## `candidateLimit` (type: `integer`):

Examine the first 1–5 search candidates. Defaults to 3. Explicit QIDs use one entity. Search can omit relevant entities beyond this limited response.

## Actor input object example

```json
{
  "queries": [
    {
      "sourceId": "team-home",
      "name": "Bayern Munich",
      "sportQid": "Q2736"
    },
    {
      "sourceId": "player-1",
      "qid": "Q1426",
      "name": "Roger Federer",
      "sportQid": "Q847"
    }
  ],
  "candidateLimit": 3
}
```

# Actor output Schema

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

Real match and standing rows, plus unbilled diagnostics. Inspect recordType/isDemo.

## `summary` (type: `string`):

Read collectionComplete, deliveryComplete and limits. Season completeness is not independently verified.

# 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 = {
    "queries": [
        {
            "sourceId": "team-home",
            "name": "Bayern Munich",
            "sportQid": "Q2736"
        },
        {
            "sourceId": "player-1",
            "qid": "Q1426",
            "name": "Roger Federer",
            "sportQid": "Q847"
        }
    ],
    "candidateLimit": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("zinin/sports-team-player-identity-matcher").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 = {
    "queries": [
        {
            "sourceId": "team-home",
            "name": "Bayern Munich",
            "sportQid": "Q2736",
        },
        {
            "sourceId": "player-1",
            "qid": "Q1426",
            "name": "Roger Federer",
            "sportQid": "Q847",
        },
    ],
    "candidateLimit": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("zinin/sports-team-player-identity-matcher").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "queries": [
    {
      "sourceId": "team-home",
      "name": "Bayern Munich",
      "sportQid": "Q2736"
    },
    {
      "sourceId": "player-1",
      "qid": "Q1426",
      "name": "Roger Federer",
      "sportQid": "Q847"
    }
  ],
  "candidateLimit": 3
}' |
apify call zinin/sports-team-player-identity-matcher --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,zinin/sports-team-player-identity-matcher"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/tnN9TeD3F5CXhWEi7/builds/eoDXifyBMDq70R7oa/openapi.json