Chemical Compound Facts & Identifier Mapping

Map explicit Wikidata chemical QIDs or a bounded list of chemical names to structured formulas, mass quantities and cross-database identifiers.

The actor uses the official Wikidata Action API. Direct QIDs are fetched in batches of at most 50. The prefilled three-QID input fits in one request, excluding retries. Optional name lookup uses one wbsearchentities search per name and one bounded candidate fetch, without pagination. It does not run SPARQL scans.

What it returns

Field	Type	Meaning
qid	string	Accepted Wikidata chemical entity ID
label	string or null	English compound label; no translation fallback
formula	string	P274 chemical formula, preserving Unicode subscripts
molarMassValue	string or null	P2067 source quantity, preserving decimal precision; leading + removed
molarMassUnit	string or null	Original P2067 unit URI, or 1 if the source is unitless
casNumber	string or null	P231 CAS number
pubchemCid	string or null	P662 PubChem compound identifier
inchiKey	string or null	P235 InChIKey
smiles	string or null	P233 canonical SMILES, falling back to P2017 isomeric SMILES
sourceUrl	string	Official Wikidata entity URL
license	string	CC0-1.0, the structured-data license

molarMassValue and molarMassUnit preserve the source's P2067 mass statement. They do not calculate a molar mass or convert units. The included sample uses dalton, so do not interpret its numeric values as measured g/mol. Missing optional properties are null. For multiple values, the first usable preferred statement is selected before normal statements; deprecated statements are ignored. This is a scalar identifier mapping rather than a complete list of alternate identifiers.

Accepted entities must be Wikidata items whose usable direct P31 classes are Q113145171 or Q11173, with a nonempty P274 formula. Entities with other P31 classes, including humans, are rejected. There is no subclass traversal. Exported compound rows contain the fields above. Raw claims, qualifiers, references, contributor details, revision history, prose descriptions and images are discarded.

Input examples

Default / prefill:

{"qids":["Q283","Q153","Q18216"],"maxItems":3}

Name lookup:

{"qids":[],"names":["aspirin","ethanol"],"maxItems":2,"searchLimit":3,"concurrency":2}

Input	Default	Limit / behavior
qids	Three sample QIDs when both selection fields are absent	Up to 500 entries; trim, uppercase, remove duplicate valid QIDs
names	Empty	Up to 10 nonempty names, 200 characters each; trim and remove exact duplicates
maxItems	3	1–500 output rows, including errors; QIDs take priority over names
searchLimit	3	1–5 candidates per name; first candidate passing the chemical gate
concurrency	2	1–5 simultaneous API requests; direct batches are sequential

An empty JSON object uses the sample QIDs. Explicit empty selection arrays fail with a clear message. Names-only programmatic input does not add default QIDs; clear the prefilled QID list in Apify Console. Unknown settings and invalid numeric settings fail the run before network work. Individual malformed QIDs produce error rows so valid siblings can continue.

Actual output example

This row was produced by the real local actor. See sample_output.json for water, ethanol and aspirin.

{
  "qid": "Q283",
  "label": "water",
  "formula": "H₂O",
  "molarMassValue": "18.02",
  "molarMassUnit": "http://www.wikidata.org/entity/Q483261",
  "casNumber": "7732-18-5",
  "pubchemCid": "962",
  "inchiKey": "XLYOFNOQVPJJNP-UHFFFAOYSA-N",
  "smiles": "O",
  "sourceUrl": "https://www.wikidata.org/wiki/Q283",
  "license": "CC0-1.0"
}

Errors and limits

An unsuccessful lookup writes a minimal row such as {"qid":"Q42","error":"NOT_CHEMICAL"}. No rejected label or arbitrary input text is echoed. A malformed QID or unsuccessful name lookup has qid: null.

Error code	Meaning
INVALID_QID	Entry is not a valid QID
NOT_FOUND	Wikidata did not return that entity
NOT_CHEMICAL	Entity does not pass the direct chemical-class gate
MISSING_FORMULA	Eligible class but no usable P274 formula
NO_CHEMICAL_MATCH	No eligible compound among the bounded search candidates
SOURCE_UNAVAILABLE	Source request failed, returned a terminal API error, or exhausted retries

Transient network failures, HTTP 429/5xx and transient API errors have at most three attempts, with exponential backoff and bounded Retry-After handling. Persistent failures become uncharged per-item errors. The compound spending limit is checked before work and before delivering compounds; after a charge reaches the limit, delivery stops.

The actor fetches only explicitly selected entities or bounded name candidates. Its output is community-maintained source data, with no independent validation of chemical values. Ambiguous names can identify an unintended compound; use QIDs for exact selection. Missing or differently classified chemicals may be rejected. There are no raw-response exports, images, Wikipedia articles or broad database crawls.

Pricing proposal

compound: $0.0015 per successfully saved compound ($1.50 per 1,000 compound events). Error rows, duplicate results and entries excluded by maxItems do not trigger this event.

This proposed result price is 25% below the most used comparable chemical lookup found in the dated Store API searches: cloud9_ai/pubchem-scraper, $0.002 per result. See PRICING.md for the query scope, evidence and event configuration. Pricing must be configured by the owner before publication; the local actor does not configure Store monetization.

FAQ

Do I need a Wikidata API key? No. These are public official API requests.

Why is a known chemical rejected? Only the two requested direct P31 classes and a usable P274 formula pass. Different classes or subclass-only membership do not pass.

Why does a mass unit say dalton? That is the source's original unit. The actor preserves it and does not silently relabel it as g/mol.

Can I get all alternate CAS numbers or PubChem CIDs? This version returns one selected value per requested property. Use the source URL to inspect alternatives.

Is a failed lookup billed as a compound? No. Only successful saved compounds trigger the compound event. Publication must avoid an additional automatic per-dataset-item event, which would charge errors too.

Use with AI agents / MCP

When the owner publishes the actor, use Apify's MCP server to run it with explicit QIDs or bounded chemical names, then retrieve its dataset. MCP lets an AI agent invoke the actor as a tool. Example task: “Look up Q283 and Q153, return their formula, CAS, PubChem CID and original mass unit, and retain the Wikidata source URL.” Treat nulls as unavailable and error codes as unsuccessful lookups. No text generation occurs inside this actor.

Local development

Use the existing C:/GritWork/earn/.venv/Scripts/python; do not install into it. From this actor directory, set APIFY_LOCAL_STORAGE_DIR to its storage directory, put the default JSON in storage/key_value_stores/default/INPUT.json, and run:

C:/GritWork/earn/.venv/Scripts/python -m src
C:/GritWork/earn/.venv/Scripts/python -m pytest -m "not live" -q -p no:cacheprovider
C:/GritWork/earn/.venv/Scripts/python -m pytest -m live -q -p no:cacheprovider
apify validate-schema

For PowerShell: $env:APIFY_LOCAL_STORAGE_DIR = "$PWD/storage". Local runs have no real event charges until Store pay-per-event pricing is configured. REPORT.md records the measured verification results and limitations.