> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oddpool.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Using Wikidata IDs

> Join canonical entities to campaign finance, tickers, rosters, and the rest of the open-data graph through their Wikidata Q-ID.

Every canonical entity carries a `wikidata_qid`. Wikidata is a free, structured database that stores hundreds of external identifiers for each entity, so the Q-ID is a ready-made join key: from one Oddpool entity you can reach a politician's campaign-finance record, a company's stock ticker and LEI, a team's league and roster, and more, without maintaining your own entity-matching layer.

The pattern is always the same: read `wikidata_qid` off the entity, then query Wikidata with it.

```python theme={null}
import requests

# Resolve an Oddpool entity to its Wikidata Q-ID
entity = requests.get(
    "https://api.oddpool.com/reference/v2/entities/lookup",
    headers={"X-API-Key": "your_api_key"},
    params={"kind": "person", "name": "Donald Trump"},
).json()

qid = entity["wikidata_qid"]   # "Q22686"
```

> [!NOTE]
>
> Wikidata asks every caller to send a descriptive `User-Agent` (an app name and contact), and it rate-limits anonymous traffic. The examples below set one. For heavy or repeated use, cache what you pull.

## Turn a Q-ID into a name and profile

The simplest call: fetch an entity's labels, description, and claims as JSON, no query language needed.

```python theme={null}
import requests

UA = {"User-Agent": "my-app/1.0 (you@example.com)"}

def wikidata_entity(qid):
    url = f"https://www.wikidata.org/wiki/Special:EntityData/{qid}.json"
    return requests.get(url, headers=UA).json()["entities"][qid]

e = wikidata_entity("Q22686")

# Some items store their label under the "mul" (multilingual) code instead of "en".
labels = e["labels"]
name = (labels.get("en") or labels.get("mul"))["value"]
description = e["descriptions"]["en"]["value"]

print(name)         # Donald Trump
print(description)  # American businessman and politician (born 1946), President of the United States ...
```

## Cross-walk an election market's candidates to campaign finance

For an election market, take each candidate outcome's `entity.wikidata_qid` and resolve them, in one request, to their campaign-finance identifiers. `wdt:P2686` is the OpenSecrets people ID and `wdt:P2390` is the Ballotpedia ID; from either you can pull filings, totals, and donor data.

```python theme={null}
import requests

UA = {"User-Agent": "my-app/1.0 (you@example.com)"}

# wikidata_qid values read off the candidate outcomes of an election event
qids = ["Q22686", "Q10853588"]
values = " ".join(f"wd:{q}" for q in qids)

query = f"""
SELECT ?person ?personLabel ?opensecrets ?ballotpedia WHERE {{
  VALUES ?person {{ {values} }}
  OPTIONAL {{ ?person wdt:P2686 ?opensecrets. }}   # OpenSecrets people ID
  OPTIONAL {{ ?person wdt:P2390 ?ballotpedia. }}   # Ballotpedia ID
  SERVICE wikibase:label {{ bd:serviceParam wikibase:language "en,mul". }}
}}"""

r = requests.get(
    "https://query.wikidata.org/sparql",
    params={"query": query, "format": "json"},
    headers=UA,
)
for row in r.json()["results"]["bindings"]:
    print(row["personLabel"]["value"],
          row.get("opensecrets", {}).get("value"),
          row.get("ballotpedia", {}).get("value"))

# Donald Trump   N00023864  Donald_Trump
# Kamala Harris  N00036915  Kamala_Harris
```

> [!TIP]
>
> To see every identifier system an entity is part of, list its external-ID properties. This is how you discover what a given entity can join to before hardcoding a property:
>
> ```sparql theme={null}
> SELECT ?propLabel ?value WHERE {
>   wd:Q22686 ?p ?value .
>   ?prop wikibase:directClaim ?p ; wikibase:propertyType wikibase:ExternalId .
>   SERVICE wikibase:label { bd:serviceParam wikibase:language "en,mul". }
> }
> ```
>
> For Q22686 this returns Ballotpedia, OpenSecrets, C-SPAN, Library of Congress, VIAF, and more.

## Get a company's ticker, exchange, and LEI

For a market on a public company, resolve the entity to its listings and legal identifiers. `p:P414` is the stock-exchange statement, with the ticker as a `pq:P249` qualifier, and `wdt:P1278` is the Legal Entity Identifier.

```python theme={null}
import requests

UA = {"User-Agent": "my-app/1.0 (you@example.com)"}

query = """
SELECT ?exchangeLabel ?ticker ?lei WHERE {
  wd:Q312 p:P414 ?s .
  ?s ps:P414 ?exchange ; pq:P249 ?ticker .
  OPTIONAL { wd:Q312 wdt:P1278 ?lei. }
  SERVICE wikibase:label { bd:serviceParam wikibase:language "en,mul". }
}"""

r = requests.get(
    "https://query.wikidata.org/sparql",
    params={"query": query, "format": "json"},
    headers=UA,
)
for row in r.json()["results"]["bindings"]:
    print(row["exchangeLabel"]["value"], row["ticker"]["value"], row.get("lei", {}).get("value"))

# Nasdaq               AAPL  HWUPKR0MPOU8FGXBT394
# Tokyo Stock Exchange 6689  HWUPKR0MPOU8FGXBT394
```

## Common cross-walks

A few properties useful for prediction-market data. Use the external-ID discovery query above to find the rest.

| System | Wikidata property | Unlocks |
| - | - | - |
| OpenSecrets people ID | `P2686` | US federal campaign finance |
| Ballotpedia ID | `P2390` | US politics and election profiles |
| Stock exchange + ticker | `P414` + `P249` | Public equities |
| Legal Entity Identifier (LEI) | `P1278` | Corporate filings and counterparty data |
| Sports league | `P118` | A team's competition |
| VIAF ID | `P214` | Library and authority records |

Wikidata publishes the [full list of external-identifier properties](https://www.wikidata.org/wiki/Wikidata:Database_reports/List_of_properties/all) and a public [SPARQL endpoint](https://query.wikidata.org).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.