PubChem PUG-REST API Skill

What this data is: Molecular structures, computed and deposited properties (molecular weight, formula, LogP, TPSA, hydrogen bonding), synonyms (including CAS numbers), safety/hazard data (GHS classification), bioassay results, and cross-references to other databases. Computed properties use standardized algorithms applied to every compound.

What this data is NOT: Not clinical trial data (use ClinicalTrials.gov). Not drug labeling (use DailyMed). Not literature citations (use PubMed). PubChem is chemical structure and property data, not clinical or regulatory content.

Core Helper Functions

import urllib.request, urllib.parse, json, time

PUG = "https://pubchem.ncbi.nlm.nih.gov/rest/pug"
PUG_VIEW = "https://pubchem.ncbi.nlm.nih.gov/rest/pug_view"

def pubchem_get(url):
    """GET request with error handling."""
    req = urllib.request.Request(url, headers={"Accept": "application/json"})
    try:
        with urllib.request.urlopen(req, timeout=20) as resp:
            return json.loads(resp.read().decode())
    except urllib.error.HTTPError as e:
        body = e.read().decode()
        try:
            fault = json.loads(body).get("Fault", {})
            return {"error": fault.get("Code",""), "message": fault.get("Message","")}
        except:
            return {"error": str(e.code), "message": body[:200]}

def compound_properties(identifier, id_type="name", properties=None):
    """Get computed properties for a compound.
    
    id_type: 'name', 'cid', 'smiles', 'inchikey', 'formula'
    properties: comma-separated property names (see Properties Reference)
    """
    if properties is None:
        properties = "MolecularFormula,MolecularWeight,IUPACName,CanonicalSMILES,InChIKey,XLogP,TPSA,HBondDonorCount,HBondAcceptorCount,RotatableBondCount,HeavyAtomCount,Complexity,Charge,ExactMass"
    
    # Formula uses fastformula endpoint
    if id_type == "formula":
        url = f"{PUG}/compound/fastformula/{urllib.parse.quote(str(identifier))}/property/{properties}/JSON"
    else:
        url = f"{PUG}/compound/{id_type}/{urllib.parse.quote(str(identifier))}/property/{properties}/JSON"
    
    data = pubchem_get(url)
    if "error" in data:
        return data
    return data.get("PropertyTable", {}).get("Properties", [])

URL Pattern

PUG-REST follows a consistent 3-part URL pattern:

/rest/pug/{domain}/{namespace}/{identifiers}/{operation}/{output}

Endpoints

1. Compound Properties (PRIMARY WORKHORSE)

Pattern: GET /compound/{namespace}/{id}/property/{properties}/JSON

Retrieve computed molecular properties. Multiple properties are comma-separated.

Namespaces for compound lookup:

Available computed properties:

Multiple CIDs: Separate with commas: /compound/cid/2244,3672,5988/property/.../JSON

2. Synonyms

Pattern: GET /compound/{namespace}/{id}/synonyms/JSON

Returns all known names for a compound, including CAS numbers, brand names, IUPAC names, and registry IDs.

def compound_synonyms(identifier, id_type="name"):
    url = f"{PUG}/compound/{id_type}/{urllib.parse.quote(str(identifier))}/synonyms/JSON"
    data = pubchem_get(url)
    if "error" in data:
        return data
    info = data.get("InformationList", {}).get("Information", [{}])[0]
    return {"cid": info.get("CID"), "synonyms": info.get("Synonym", [])}

3. Description

Pattern: GET /compound/cid/{cid}/description/JSON

Returns text descriptions from various sources (ChEBI, OEHHA, EPA, etc.).

def compound_description(cid):
    url = f"{PUG}/compound/cid/{cid}/description/JSON"
    data = pubchem_get(url)
    if "error" in data:
        return data
    return [{"source": d.get("DescriptionSourceName",""),
             "description": d.get("Description","")}
            for d in data.get("InformationList",{}).get("Information",[]) if d.get("Description")]

4. Similarity Search (2D Fingerprint)

Pattern: GET /compound/fastsimilarity_2d/{namespace}/{id}/property/.../JSON?Threshold={pct}&MaxRecords={n}

Finds structurally similar compounds by 2D Tanimoto fingerprint similarity.

def similarity_search(identifier, id_type="cid", threshold=90, max_records=10, properties=None):
    if properties is None:
        properties = "IUPACName,MolecularWeight,MolecularFormula"
    url = (f"{PUG}/compound/fastsimilarity_2d/{id_type}/{urllib.parse.quote(str(identifier))}"
           f"/property/{properties}/JSON?Threshold={threshold}&MaxRecords={max_records}")
    data = pubchem_get(url)
    if "error" in data:
        return data
    return data.get("PropertyTable", {}).get("Properties", [])

5. Substructure Search

Pattern: GET /compound/fastsubstructure/{namespace}/{id}/cids/JSON?MaxRecords={n}

Finds compounds containing a given substructure.

def substructure_search(smiles, max_records=10):
    url = (f"{PUG}/compound/fastsubstructure/smiles/{urllib.parse.quote(smiles)}"
           f"/cids/JSON?MaxRecords={max_records}")
    data = pubchem_get(url)
    if "error" in data:
        return data
    return data.get("IdentifierList", {}).get("CID", [])

6. Formula Search

Pattern: GET /compound/fastformula/{formula}/property/.../JSON?MaxRecords={n}

Finds all compounds with a given molecular formula.

def formula_search(formula, max_records=10, properties=None):
    if properties is None:
        properties = "IUPACName,MolecularWeight"
    url = f"{PUG}/compound/fastformula/{formula}/property/{properties}/JSON?MaxRecords={max_records}"
    data = pubchem_get(url)
    if "error" in data:
        return data
    return data.get("PropertyTable", {}).get("Properties", [])

7. Bioassay Summary for a Compound

Pattern: GET /compound/cid/{cid}/assaysummary/JSON

Returns all bioassay results for a compound (active/inactive calls across assays).

def assay_summary(cid):
    url = f"{PUG}/compound/cid/{cid}/assaysummary/JSON"
    data = pubchem_get(url)
    if "error" in data:
        return data
    table = data.get("Table", {})
    columns = table.get("Columns", {}).get("Column", [])
    rows = table.get("Row", [])
    return {"columns": columns, "row_count": len(rows),
            "sample_rows": [r.get("Cell",[]) for r in rows[:5]]}

8. Cross-References

Pattern: GET /compound/cid/{cid}/xrefs/{xref_type}/JSON

9. Structure Images

Pattern: GET /compound/{namespace}/{id}/PNG or /SVG

Returns 2D structure diagram. Use directly as an image URL.

def structure_image_url(cid, fmt="PNG", size=300):
    return f"{PUG}/compound/cid/{cid}/{fmt}?image_size={size}x{size}"

10. PUG-View: Curated Summary Sections

Pattern: GET /pug_view/data/compound/{cid}/JSON?heading={heading}

Returns curated data organized by section headings. Useful for safety, pharmacology, and toxicology data that is NOT in computed properties.

def pug_view_section(cid, heading):
    url = f"{PUG_VIEW}/data/compound/{cid}/JSON?heading={urllib.parse.quote(heading)}"
    data = pubchem_get(url)
    if "error" in data:
        return data
    return data.get("Record", {}).get("Section", [])

Key headings:

Common Workflows

Quick Compound Profile

def compound_profile(name):
    """Get a complete profile for a compound by name."""
    props = compound_properties(name, id_type="name",
        properties="MolecularFormula,MolecularWeight,IUPACName,CanonicalSMILES,InChIKey,XLogP,TPSA,HBondDonorCount,HBondAcceptorCount,RotatableBondCount,Complexity,Charge,ExactMass")
    if isinstance(props, dict) and "error" in props:
        return props
    if not props:
        return {"error": "No results"}
    
    p = props[0]
    cid = p.get("CID")
    
    time.sleep(0.25)
    syns = compound_synonyms(str(cid), id_type="cid")
    synonym_list = syns.get("synonyms", [])[:10] if not isinstance(syns, dict) or "error" not in syns else []
    
    return {
        "cid": cid,
        "name": p.get("IUPACName"),
        "formula": p.get("MolecularFormula"),
        "molecular_weight": p.get("MolecularWeight"),
        "smiles": p.get("CanonicalSMILES"),
        "inchikey": p.get("InChIKey"),
        "xlogp": p.get("XLogP"),
        "tpsa": p.get("TPSA"),
        "hbd": p.get("HBondDonorCount"),
        "hba": p.get("HBondAcceptorCount"),
        "rotatable_bonds": p.get("RotatableBondCount"),
        "complexity": p.get("Complexity"),
        "synonyms": synonym_list,
        "image_url": structure_image_url(cid) if cid else None
    }

Lipinski Rule of Five Check

def lipinski_check(name):
    """Check Lipinski's Rule of Five for drug-likeness."""
    props = compound_properties(name, id_type="name",
        properties="MolecularWeight,XLogP,HBondDonorCount,HBondAcceptorCount")
    if isinstance(props, dict) and "error" in props:
        return props
    if not props:
        return {"error": "No results"}
    p = props[0]
    violations = 0
    checks = {
        "MW <= 500": float(p.get("MolecularWeight",0)) <= 500,
        "XLogP <= 5": (p.get("XLogP") or 0) <= 5,
        "HBD <= 5": (p.get("HBondDonorCount") or 0) <= 5,
        "HBA <= 10": (p.get("HBondAcceptorCount") or 0) <= 10,
    }
    violations = sum(1 for v in checks.values() if not v)
    return {"compound": p.get("CID"), "checks": checks,
            "violations": violations, "drug_like": violations <= 1}

CAS Number Lookup

def cas_to_compound(cas_number):
    """Look up a compound by CAS registry number."""
    return compound_properties(cas_number, id_type="name",
        properties="IUPACName,MolecularFormula,MolecularWeight,CanonicalSMILES,InChIKey")

Compare Multiple Compounds

def compare_compounds(names):
    """Compare properties across multiple compounds."""
    all_props = []
    for name in names:
        props = compound_properties(name, id_type="name",
            properties="MolecularFormula,MolecularWeight,XLogP,TPSA,HBondDonorCount,HBondAcceptorCount,RotatableBondCount")
        if isinstance(props, list) and props:
            all_props.append({"query": name, **props[0]})
        time.sleep(0.25)
    return all_props

Gotchas and Best Practices

1. SMILES Strings Must Be URL-Encoded (MOST COMMON MISTAKE)

SMILES contain characters like =, (, ), # that break URLs. Always URL-encode: urllib.parse.quote(smiles). The = in CC(=O) must become CC(%3DO).

2. Error Responses Use "Fault" Object, Not HTTP Status

PubChem returns HTTP 200 for some errors with a Fault JSON object containing Code and Message. Common codes: PUGREST.NotFound (compound not found), PUGREST.BadRequest (malformed query), PUGREST.ServerBusy (rate limited).

3. Rate Limit: 5 req/sec, 400 req/min

Stricter than most NCBI APIs. Use time.sleep(0.25) between calls. Exceeding limits returns PUGREST.ServerBusy with a "Please throttle your requests" message.

4. CAS Numbers Work Through the Name Namespace

PubChem resolves CAS numbers like names: /compound/name/50-78-2/... correctly maps to aspirin (CID 2244). No special endpoint needed.

5. Name Lookups May Return Multiple CIDs

Ambiguous names can match multiple compounds. The property endpoint returns the first match. Use /compound/name/{name}/cids/JSON to see all matches, then query by specific CID.

6. Many Common Chemical Names Do NOT Resolve (CRITICAL)

PubChem's name resolution is surprisingly picky. Many names that seem obvious fail with PUGREST.NotFound:

• "ascorbic acid", "vitamin C", "L-ascorbic acid" all fail; CAS 50-81-7 works
• "lead acetate", "lead(II) acetate" fail; CAS 301-04-2 works
• Salt forms like "acesulfame potassium", "acesulfame K" fail; base compound "acesulfame" works
• Parenthetical qualifiers and Roman numerals in names often cause failures

Best practice: When a name lookup fails, try in this order: (1) CAS number, (2) base compound without salt/counter-ion, (3) simplified name, (4) SMILES or InChIKey if available. CAS numbers are the most reliable name-type identifier for PubChem lookups.

7. Formula Search Returns All Isomers

Searching by formula (e.g., C9H8O4) returns all compounds with that formula, not just the one you expect. Use MaxRecords to limit results, then filter by name or other properties.

8. PUG-View is Separate from PUG-REST

Safety/hazard data, pharmacology summaries, and toxicity data are in PUG-View (/rest/pug_view/), not PUG-REST (/rest/pug/). PUG-REST has computed properties; PUG-View has curated content organized by headings.

9. 3D Properties Require 3D Conformers

Properties like Volume3D, FeatureCount3D, and steric quadrupoles require computed 3D conformers. Not all compounds have them. These return null/missing if unavailable.

10. Bioassay Summary Can Be Very Large

The /assaysummary endpoint for well-studied compounds (like aspirin with 4,900+ assay results) returns large payloads. Process in batches or use column filtering.

11. Response Property Keys Differ from Request Names

Some property names in the URL do not match the keys in the JSON response. Most notably: requesting CanonicalSMILES returns a key called ConnectivitySMILES, and requesting IsomericSMILES returns a key called SMILES. Always check the actual keys in the response rather than assuming they match the request parameter.

12. Description Sources Vary Widely by Compound

The /description endpoint returns text from external databases (ChEBI, OEHHA, EPA, etc.). Well-known drugs may have only 1 or 2 sources. Do not assume a minimum number of descriptions will be available.

13. Spaces in Compound Names Must Use %20, Not +

Compound names are in the URL path, not the query string. In URL paths, + is a literal plus sign, not a space. bisphenol+A fails with "No CID found"; bisphenol%20A succeeds. Always use urllib.parse.quote(name) which produces %20 for spaces.

14. PUG-View Sections Are Deeply Nested

Safety/GHS data is typically 3-4 levels deep: "Safety and Hazards" > "Hazards Identification" > "GHS Classification" > specific items. Use recursive traversal when searching for specific headings, not fixed-depth indexing.

Troubleshooting