/chembl-database-bioactivity

name: chembl-database-bioactivity
description: Query ChEMBL (2M+ compounds, 19M+ bioactivity measurements, 13K+ targets) via the public REST/JSON API with plain `requests` — no SDK install required. Search compounds, retrieve IC50/Ki/EC50 bioactivities, find target inhibitors, run SAR, access drug mechanism/indication data.
license: CC-BY-SA-3.0
metadata:
  quick_use: 'one compound: GET https://www.ebi.ac.uk/chembl/api/data/molecule.json?pref_name__iexact={INN} -> molecules[0].molecule_chembl_id (empty list if unknown). molecule/search.json?q= ranks salts and analogs first (osimertinib -> the mesylate CHEMBL3545063 before the parent CHEMBL3353410); for a brand or salt name, search and report molecule_hierarchy.parent_chembl_id. EBI intermittently returns a 500 HTML page: retry once after a few seconds. Cite https://www.ebi.ac.uk/chembl/explore/compound/{ID}'

ChEMBL Database — Bioactivity Queries

> **Why no SDK?** The `chembl_webresource_client` package is convenient sugar over a public, no-auth REST/JSON API at `https://www.ebi.ac.uk/chembl/api/data/`. When the SDK is unavailable, every operation can be reproduced with plain `requests` and URL parameters. This SKILL.md uses the REST path throughout so the code runs in any environment with `requests` installed. Django-style filter syntax (`field__icontains=…`, `field__lte=…`, `field__range=a,b`) works as URL query parameters.

Overview

ChEMBL is EMBL-EBI's bioactive molecule database: 2M+ compounds, 19M+ bioactivity measurements (IC50, Ki, EC50, Kd, …), 13K+ targets. The REST API at `https://www.ebi.ac.uk/chembl/api/data/` returns JSON (append `.json`) or XML/YAML, requires no authentication, and supports Django-style query filters via URL parameters plus cursor-style pagination via `page_meta.next`.

When to Use

• Finding compounds by name, ChEMBL ID, or physicochemical properties
• Querying bioactivity data (IC50, Ki, EC50) for specific targets
• Performing similarity or substructure searches using SMILES
• Retrieving drug mechanisms of action and clinical indications
• Identifying inhibitors, agonists, or bioactive molecules for a target
• Analyzing structure-activity relationships (SAR) across compound series
• Filtering molecules by Lipinski rule-of-5 or other drug-likeness criteria
• For general cheminformatics (SMILES manipulation, fingerprints, descriptors) use `rdkit-cheminformatics` instead
• For an alternative compound database (NIH, broader coverage) use `pubchem-compound-search`

Prerequisites

• **Python packages**: `requests` (only requirement). Optional: `pandas` for tabular analysis.
• **No API key required**: ChEMBL is freely accessible.
• **Rate limits**: No published hard limit. The infrastructure is shared — add `time.sleep(0.2-0.5)` between requests in batch loops; back off on HTTP 429.

pip install requests
# Optional, for DataFrame work:
pip install pandas

Quick Start

import requests

BASE = "https://www.ebi.ac.uk/chembl/api/data"

# Retrieve a molecule by ChEMBL ID
r = requests.get(f"{BASE}/molecule/CHEMBL25.json", timeout=15)
r.raise_for_status()
aspirin = r.json()
print(f"{aspirin['pref_name']}: MW={aspirin['molecule_properties']['mw_freebase']}")
# ASPIRIN: MW=180.16

# Search targets by full name (acronyms like 'EGFR' don't match pref_name — use full term)
r = requests.get(
    f"{BASE}/target.json",
    params={"pref_name__icontains": "epidermal growth factor receptor",
            "target_type": "SINGLE PROTEIN", "limit": 5},
    timeout=15,
)
targets = r.json()["targets"]
print(f"EGFR-like targets: {len(targets)}, first={targets[0]['target_chembl_id']}")

# Potent bioactivities: EGFR (CHEMBL203) IC50 <= 100 nM
r = requests.get(
    f"{BASE}/activity.json",
    params={"target_chembl_id": "CHEMBL203",
            "standard_type": "IC50",
            "standard_value__lte": 100,
            "standard_units": "nM",
            "limit": 5},
    timeout=30,
)
data = r.json()
print(f"EGFR IC50 ≤ 100 nM records: {data['page_meta']['total_count']}")

Key Concepts

Filter Operators (Django-style, as URL parameters)

The SDK's `field__operator=value` syntax maps 1:1 to URL query parameters. Use `&` to combine filters.

| Operator | URL pattern | Example URL fragment | |----------|-------------|----------------------| | `__exact` | `field=value` | `target_type=SINGLE+PROTEIN` | | `__iexact` | `field__iexact=value` | `pref_name__iexact=aspirin` | | `__contains` / `__icontains` | `field__icontains=value` | `pref_name__icontains=kinase` | | `__startswith` / `__endswith` | `field__startswith=Epi` | `pref_name__endswith=nib` | | `__gt` / `__gte` / `__lt` / `__lte` | `field__lte=100` | `standard_value__lte=100` | | `__range` | `field__range=lo,hi` | `molecule_properties__mw_freebase__range=300,500` | | `__in` | `field__in=a,b,c` | `standard_type__in=IC50,Ki,Kd` | | `__isnull` | `field__isnull=False` (Python `False`/`True` strings) | `pchembl_value__isnull=False` | | `__regex` | `field__regex=…` | `pref_name__regex=^EGF.*kinase$` | | `__search` | `field__search=…` | `description__search=apoptosis` |

When passed via `requests.get(..., params={...})`, the library handles URL encoding automatically (including the commas in `__range` and `__in`).

Core Endpoints

All endpoints accept `.json`, `.xml`, or `.yaml` suffix. JSON is the default below.

| Endpoint URL | Returns | Key fields | |--------------|---------|------------| | `/molecule/{chembl_id}.json` | Compound by ID | `pref_name`, `molecule_chembl_id`, `molecule_properties`, `molecule_structures` | | `/molecule.json?<filters>` | Compound search | paginated `molecules[]` | | `/target/{chembl_id}.json` | Target by ID | `pref_name`, `target_type`, `organism`, `target_components` | | `/target.json?<filters>` | Target search | paginated `targets[]` | | `/activity.json?<filters>` | Bioactivity records | paginated `activities[]` | | `/assay.json?<filters>` | Assay details | paginated `assays[]` | | `/drug.json?<filt