omnilab/wikidata

Wikidata, through the Action API (https://www.wikidata.org/w/api.php), for omnisense/omnilab: any item by its Q-number, by a science base's identifier (PubChem, ChEBI, CAS, UniProt, NCBI, GBIF, SIMBAD...) or by label - its labels in a language, its cross-references, a few properties with units - as an entity; a search, narrowed to a domain when asked. No key.

Installation

composer require omnilab/wikidata

use Omnilab\Wikidata\WikidataSourceFactory;

$wikidata = (new WikidataSourceFactory($httpClient))->create([
    'mailto' => 'support@glitchr.io',  // optional, but Wikimedia wants to reach the caller
    'language' => 'en',                // optional
    'synonyms' => 20,                  // optional
]);

With the Symfony bundle, the factory is registered as wikidata (see the core's docs).

Credentials

None: the Action API takes no key. Wikimedia's User-Agent policy asks every client to name itself and a way to reach its operator (403 otherwise): the default User-Agent names the project, mailto adds the address, user_agent names an application of its own.

Options

The factory's options, with the defaults it applies (WikidataSourceFactory):

Capabilities

capabilities() answers entity, search, cross_references; an operation it does not answer throws NotSupportedException before any call.

Calls

Every call goes to the Action API, https://www.wikidata.org/w/api.php, in JSON (formatversion=2). The SPARQL endpoint (query.wikidata.org) is not used: CirrusSearch's haswbstatement finds an item by an identifier in one plain API call.

Then one wbgetentities&props=labels for the labels of the items' classes (P31, the kind) and of the units not in the source's table; a label read once is kept for the source's life.

The value is looked for as Wikidata writes it: GO:0005829, HP:0001250, MONDO_0017146 (the core keeps their digits), a water site's NWIS number without USGS-. An HGNC id or a MIM number is looked for among the items that carry no UniProt accession (haswbstatement:P354=4827 -haswbstatement:P352): HBB's gene (Q14905542) and its protein (Q424422) both carry HGNC:4827, and the gene is what HGNC names. A GO term, an InterPro entry, a Pfam family or an EC number is looked for among the items that are neither a gene (P351) nor a protein (P352): the class's own item.

An identifier two items carry names neither: null (CAS 7732-18-5 is on water and on distilled water: so are some ISC-GEM earthquakes, iscgem900408). An identifier of a scheme the source does not look up - an InChI, a PDB code - is refused before any call; unknown is null.

A domain narrows a search to the items that carry one of these statements:

What an item holds

id (its Q-number), label, description and synonyms (its aliases, those that are identifiers left out, 20 by default) in the language asked - mul (the names alike in every language) and Wikidata's fallbacks after it; kind (the label of its first class, P31: caffeine is a "type of chemical entity", the cougar a "taxon"); domain (told by its first identifier of the table below, taxonomy for an item with a taxon name, other without); url (its page); image (its chemical structure, P117, else its image, P18, as a Commons file address); place (its coordinates on Earth, P625); time (its point in time, P585, when given to the day).

Of each property, the values of its best statements: the preferred ones when there are, else the normal ones; never the deprecated, nor "unknown value". Qualifiers (the temperature of a pKa, a solvent) and references are not read.

identifiers, in this order:

On a gene's or a protein's item (one that carries P351 or P352), a GO term, an InterPro entry, a Pfam family or an EC number is a class it belongs to, not itself: it goes to related - go, domain, domain, enzyme - and the Collector does not follow it (T7 DNA polymerase, Q7669118: uniprot:P00581 its identifier, ec:2.7.7.7 and interpro:IPR034749 related). Two kinases that share EC 2.7.10.1 are not one kinase. On the class's own item (hydrolase activity, Q14353168: GO:0016787, EC 3.-.-.-) they are identifiers.

related, always:

Neither is looked up: the item that carries a structure is not that structure. The Collector does not enter the COD or the Materials Project from Wikidata; $item->related('structure') gives their ids.

Properties:

A unit is the symbol of a table of 29 common units (Da, °C, K, °F, g/cm³, kg, m, km, s, a, km/h, Pa, ly, pc, au, M☉, %...), else the unit item's label in the language asked. A bound (± ) becomes the Quantity's uncertainty, half the interval.

What Wikidata does not give here

• PDB structures (P638) are not cross-references: on caffeine they are the 22 structures that hold it - none is caffeine itself, so the Merger must not take one for it.
• GBIF's two keys are one scheme read from two properties: P14607, the key of GBIF's taxonomy since June 2026 (the Catalogue of Life eXtended Release: ^[23456789BCDFGHJKLMNPQRSTVWXYZ]{1,6}$), and P846, the legacy Backbone's number. An item gives both when it has both, P14607's first; a key is looked for in P14607, a number in P846. On 2026-10-15, 2663 items carried P14607 (the bottlenose dolphin, 59R5F), not the lion (Q140: P846 5219404 only): a lookup by the new key of a taxon not yet given one is null, by its number it is found - the GBIF source gives both.
• P3196, the USGS earthquake ID, was on 1,511 items on 2026-10-15 (1,531 statements: 17 items carry several, 16 ids are on two items): us... ids for most (967), ISC-GEM's for 466, and for the great historical earthquakes the ids of the catalogues ComCat keeps (official...: Tohoku 2011, Sumatra 2004, Chile 2010, San Francisco 1906) - which the core's usgs.event scheme reads, and the USGS answers. One statement is an "unknown value", which is never read. The magnitude Wikidata gives is usually on the moment scale (P2527); its time is a day (P585, no hour), its place the epicentre (P625).
• Not read: P1554 (UBERON ID, not Orphanet's: Orphanet's is P1550); P6754 (OBIS ID: OBIS keys its taxa by WoRMS's AphiaIDs, and P850 gives them - one of 88 items sampled on 2026-10-16 carried two different values, so the OBIS property is not taken for the worms scheme); P638 (PDB, above); P704 and P705 (Ensembl transcripts and proteins: other things than the gene). No Wikidata property names a STRING protein, a QuickGO annotation, an Open Targets or a GWAS Catalog record, a KEGG pathway, a Rhea reaction, an OQMD entry, an EMSC event, a CO-OPS station, a NED object, a VizieR table, a DONKI event or a Launch Library launch (searched on 2026-10-16).
• No other statement is read: the item-valued ones (subclass of, has part...), the qualifiers, the references, the sitelinks. No SPARQL, no lexemes, no properties as entities.
• The search index (CirrusSearch) follows edits after a delay: a statement just added may not be found by haswbstatement yet, while wbgetentities already gives it.

Example

<?php

require __DIR__.'/vendor/autoload.php';

use Omnilab\Model\Domain;
use Omnilab\Model\Identifier;
use Omnilab\Model\Scheme;
use Omnilab\Source\Query;
use Omnilab\Wikidata\WikidataSourceFactory;
use Symfony\Component\HttpClient\HttpClient;

$wikidata = (new WikidataSourceFactory(HttpClient::create()))->create(['mailto' => 'you@example.org', 'language' => 'fr', 'synonyms' => 3]);

$caffeine = $wikidata->entity(Identifier::cid(2519));   // by PubChem's CID (P662)
echo $caffeine->label, ' (', $caffeine->id, ', ', $caffeine->kind, '): melting point ', $caffeine->property('melting_point'), ', ChEBI ', $caffeine->identifier(Scheme::CHEBI), ', CAS ', $caffeine->identifier(Scheme::CAS), "\n";

$page = $wikidata->search(new Query('Betelgeuse', Domain::ASTRONOMY, limit: 2));
foreach ($page as $item) {
    echo '  ', $item->id, '  ', $item->label, '  SIMBAD ', $item->identifier(Scheme::SIMBAD), "\n";
}

caféine (wikidata:Q60235, type d'entité chimique): melting point 234 °C, ChEBI 27732, CAS 58-08-2
  wikidata:Q12124  Bételgeuse  SIMBAD * alf Ori
  wikidata:Q79176630  TYC 716-905-1  SIMBAD TYC 716-905-1

(as answered on 2026-10-27 in French: six calls, 0.3 s apart - the search by haswbstatement:P662=2519, the item, its classes' and units' labels, then the search narrowed to astronomy and its items)

# config/packages/omnilab.yaml
omnilab:
    sources:
        wikidata: { factory: wikidata, options: { mailto: '%env(OMNILAB_MAILTO)%', language: en } }

Errors

Every call goes through HttpSource: a 404 or a 410 (and a 204) is null - an empty page for a list -; a 429 is a RateLimitedException (retryAfter from Retry-After); a 5xx, a time-out or a host that does not answer an UnavailableException; any other 4xx a ProviderException with its status and what the service said; an answer that is not JSON a ProviderException, a web page answered for JSON an UnavailableException.

The Action API's own errors come in a 200's error: maxlag and ratelimited are a RateLimitedException (its lag as retryAfter), the codes that mean nothing found an empty answer, any other a ProviderException with its code and info. A 403 (no User-Agent that names the caller) is a ProviderException. Before any call: an identifier of a scheme it does not look up (an InChI, a PDB code) (NotSupportedException).

Verified, and not

Against the real service on 2026-10-15, without a key: every property number above, read from Wikidata (wbgetentities&ids=P662|P683|...), and every unit and class item of the tables; caffeine (Q60235) in English and French with its identifiers, units and classes; caffeine found by its PubChem CID, its ChEBI id, its CAS number, its InChIKey and its label; the cougar (Q35255) with its NCBI, GBIF and iNaturalist ids; the bottlenose dolphin (Q174199) found by its P14607 key 59R5F and by its P846 number 2440447, the lion by its number but not by its key 4CGXP (no P14607 on it); CAS 7732-18-5 on two items; the 2025 Myanmar earthquake (Q133574091) found by its USGS id us7000pn9s, its moment magnitude 7.7, its day and epicentre, and iscgem900408 on two items; every P3196 value (read through the query service, once, for this count) matched against the usgs.event scheme: all read; that evening 51 Peg b (Q242309) with its SIMBAD and NASA Exoplanet Archive names (* 51 Peg b, 51 Peg b), Barnard's star (Q14268) found by its Gaia DR3 source_id 4472832130942575872 (P13228), glycolysis (Q45317172) by its Reactome id R-HSA-70171 (P3937), and the first 20,000 P3937 values all of the reactome scheme's shape; an item that does not exist (no-such-entity); a search by label and its second page; a search among chemistry (46 items); the domain filters (Tohoku and Etna among earth, the Myanmar earthquake first for "Myanmar" with P3196, Andromeda among astronomy, TP53 among biology, "puma" among taxonomy); the answer while the servers lag (maxlag, 200 with Retry-After: 5, asked with maxlag=-1); a call without a User-Agent, or with a library's generic one, refused (403). The fixtures in Tests/Fixtures/ are its answers, the statements' references and qualifiers taken out.

On 2026-10-16: every property added that day read from Wikidata (wbgetentities&ids=P354|P492|...) with its formatter, its format and its examples, and each value form checked against the core's scheme (P1554, given for Orphanet, is UBERON's: P1550 taken); the number of items of each (haswbstatement:P...'s total); the HBB gene (Q14905542) found by HGNC:4827 with the protein's item left out (both carry it), sickle-cell disease (Q185034) by MONDO_0017146, cytosol (Q220599) by GO:0005829, Apophis (Q118931) by its MPC number 99942, the American Robin (Q460967) by eBird's amerob, the proton mass (Q97275155) by CODATA's mp, BRAF V600E (Q21851559) with its ClinVar and dbSNP ids, T7 DNA polymerase (Q7669118) with its EC number and InterPro entry related, niobium-germanium (Q7039311) and sodium chloride (Q2314) with their COD structure and Materials Project material related. The Collector from Wikidata into HGNC (the HBB gene: 3 calls, 3.1 s; and back, 3 calls, 2.1 s), into the MPC (Apophis: 5 calls, 3.9 s), into eBird, ITIS, WoRMS and the Catalogue of Life (the American Robin: 13 calls, 7.3 to 15.5 s in two runs) and into CODATA (the proton mass: 4 calls, 1.7 s). The fixtures of that day are its answers, likewise.

Again on 2026-10-27, in French: caffeine by its PubChem CID (its melting point, ChEBI and CAS ids), the search for Betelgeuse narrowed to astronomy (the example above).

Not verified: a 429 of Wikimedia's rate limits (the handling is the core's, Retry-After read); the ratelimited API error, handled as a RateLimitedException as the etiquette describes it; the delay of the search index after an edit.

Responsibility

This package is an independent, unofficial client: it is not affiliated with, endorsed by or sponsored by the Wikimedia Foundation or Wikidata. Wikidata's structured data are under CC0; Wikimedia's User-Agent policy and rate limits apply, as the README's Terms of use says. Whoever runs the package is responsible for complying with them and for any use made of what it returns: see the README's Responsibility section.