ChEMBL logo


ChEMBL Statistics
  Loading Statistics...

ChEMBL Web Services

Web Service Update (February 2015)

A new version of the ChEMBL web services are now available, which expose significantly more data from the under underlying ChEMBL database and introduce new functionality. In addition to the web services that provide access to ChEMBL data, web services that provide access to commonly used cheminformatic methods are also available.

Web Services Documentation

Online interactive documentation is available for both ChEMBL web services:

ChEMBL Web Service Type Documentation
Cheminformatic Utils (aka 'ChEMBL Beaker')

ChEMBL Data Web Services

The updated ChEMBL web services are not compatible with the previous version of the ChEMBL web services. For this reason we still provide access to the earlier version and the older documentation. We encourage users to migrate any applications using the previous ChEMBL web services to the updated version described on this page.

Getting Started

To best way to get started is to have a look at some example URLs requesting data from the ChEMBL web services. The table below provides a list of examples and a description of the data being returned.

Description Example URL
Return all molecules
Keyword search for targets that contain 'cyclin' in pref_name
Return molecules with molecular weight <= 300
Return molecules with molecular weight <= 300 AND pref_name ends with nib
Return image for CHEMBL25
Substructure search with SMILES CC(=O)Oc1ccccc1C(=O)O (Aspirin)
Similarity search with SMILES CN1C(=O)C=C(c2cccc(Cl)c2)c3cc(ccc13)[C@@](N)(c4ccc(Cl)cc4)c5cncn5C with 80% tanimoto similarity cut off[C@@](N)(c4ccc(Cl)cc4)c5cncn5C/80


The following table provides a list of all ChEMBL web service resources currently available.

Resource Name Description URL
Activity Activity values recorded in an Assay
Assay Assay details as reported in source Document/Dataset
ATC WHO ATC Classification for drugs
BindingSite Target binding site definition
Biotherapeutic Biotherapeutic molecules, which includes HELM notation and sequence data
CellLine Cell line information
ChEMBLIdLookup Look up ChEMBL Id entity type
Document Document/Dataset from which Assays have been extracted
Image Graphical (png, svg, json) representation of Molecule
Mechanism Mechanism of action information for FDA-approved drugs
Molecule Molecule information, including properties, structural representations and synonyms
MoleculeForm Relationships between molecule parents and salts
ProteinClassification Protein family classification of TargetComponents
Substructure Molecule substructure search
Similarity Molecule similarity search
Source Document/Dataset source
Target Targets (protein and non-protein) defined in Assay
TargetComponent Target sequence information (A Target may have 1 or more sequences)

Meta Data and Pagination

It is now possible to download all data from a specific ChEMBL web service resource. This is made possible by returning responses from the web services in 'pages', which can be navigated through using a 'page_meta' section. The 'page_meta' section includes information about total number of hits, total number of pages and links to the next and previous pages. An example 'page_meta' section is displayed below:

"page_meta": {

    "limit": 20,
    "next": "/chembl/api/data/activity.json?limit=20&offset=20",
    "offset": 0,
    "previous": null,
    "total_count": 13520737

To download all ChEMBL activity endpoints (>13 million), the following URL can be used: By inspecting the the 'page_meta' section the link to page 2 can be found, e.g.

Filtering and Ordering

It is possible to apply search filters to all resource requests using a URL friendly query language. For example, it is possible to return all ChEMBL targets that contain the term 'kinase' in the pref_name attribute with the following URL:

The pattern for applying a filter is as follows:[resource]?[field]__[filter_type]=[value]

Examples of other filter type are listed in the table below.

Filter Type Description Example URL
exact (iexact) Exact match with query
contains (icontains) Wild card search with query
startswith (istartswith) Starts with query
endswith (iendswith) Ends with query
regex (iregex) Regular expression query|cdk2)
gt (gte) Greater than (or equal)
lt (lte) Less than (or equal)
range Within a range of values,500
in Appears within list of query values,CHEMBL941,CHEMBL1000
isnull Field is null

To order the results returned by a particular field the 'order=[field]' argument as added to a request. For example a user can sort targets based on the pref_name using the following URL:

The default ordering is in ascending order. To return the results in descending orede place a '-' before the field name:

Note that it is possible combine order_by and filter arguments:

Chemical Searching

The 'Substructure' and 'Similarity' web service resources allow for the chemical content of ChEMBL to be searched. Similar to the other resources, these search based resources except filtering, paging and ordering arguments. These methods accept SMILES, InChI Key and molecule ChEMBL_ID as arguments and in the case of similarity searches an additional identity cut-off is needed. Some example molecule searches are provided in the table below.

Chemical Search Description Example URL
Substructure search for against ChEMBL using aspirin SMILES string
Substructure search for against ChEMBL using aspirin CHEMBL_ID
Substructure search for against ChEMBL using aspirin InChI Key
Similarity (80% cut off) search for against ChEMBL using aspirin SMILES string
Similarity (80% cut off) search for against ChEMBL using aspirin CHEMBL_ID
Similarity (80% cut off) search for against ChEMBL using aspirin InChI Key

Searching with InChI key is only possible for InChI keys found in the ChEMBL database. The system does not try and convert InChI key to a chemical representation.

Molecule Images

The Image resource returns a graphical representation of a ChEMBL molecule. Unlike the other resources it does not except filtering and paging arguments, but does except image specific arguments. These are defined in the table below.

Image Argument Description Allowed Values Default Value Example URL
format Image format png, svg and json png
dimensions Size of image in pixels 1-500 500
ignoreCoords Choose to use or ignore coordinates in ChEMBL molfiles 1 or 0 0 (Use ChEMBL molfile coordinates)
engine Chemical toolkit used to generate image rdkit or indigo rdkit

Web Service Client

To help users get started with using the updated ChEMBL web services the existing web service client has also been released. This is written in the Python programming language and is available to download from GitHub.

Example Queries

The table below provides a list of example searches a user may wish to carry out using the ChEMBL web services. The aim of the list is highlight the type of data that can be retrieved from ChEMBL using the web services. The examples can be adapted, extended and chained togther to build up more complex workflows.

Description Example URL
Get all approved drugs
Get all molecules in ChEMBL with no Rule-of-Five violations
Get all biotherapeutic molecules
Get all functional/phenotypic assays (assay_type=F), from the literature (src_id 1)
Get all binding assays (assay_type=B), which also contain the term 'insulin'
Get all Clearance activity values (standard_type=CL), for rat, mouse and human,Rattus%20norvegicus,Mus%20musculus
Get all cell lines, which end with the term 'carcinoma'
Get all mechanism of action details muscarinic acetylcholine receptor antagonists
Get all targets (single protein, protein complexes, protein families etc.), which contain UniProt accession Q13936
Get the entity type for CHEMBL1000

Use Cases

The following use cases is provided as an example of how it is possible chain together ChEMBL web service calls to awnser to complicated questions usin ChEMBL data.

Investigating the potency of approved drugs against their efficacy targets

Since ChEMBL includes both mechanism of action information for approved drugs and pharmacology data from published assays, it is interesting to combine this information and investigate the potency of a drug against its efficacy target. This might be done either to confirm or refute the proposed target assignment, or to better understand how the in-vitro potency of a compound might relate to clinical efficacy or ADMET properties. The following example shows how this type of analysis could be carried out using the ChEMBL web services.

  1. Use the molecule end point to retrieve a list of approved drugs (max_phase=4):

    Using ChEMBL_20, this will retrieve 2795 drugs in total. We will use CHEMBL998 (loratadine) as an example, but the same workflow could be repeated for the others.

  2. Use the mechanism end point to retrieve the mechanism of action and target of each drug:

    Loratadine is reported to be a histamine H1 receptor antagonist, represented by the ChEMBL target CHEMBL231.

  3. Use the assay end point to identify any binding assays (assay_type=B) for the human histamine H1 receptor:

    Note the relationship_type=D filter restricts the results to assays where we are confident that the human receptor was tested and not an orthologue. A total of 213 assays are identified. We will take CHEMBL1909156 as an example.

  4. Combine the results of the above queries to identify any potency measurements for loratadine in these assays:

    This assay reports an IC50 value of 170nM and a Ki measurement of 20nM for loratadine against the histamine H1 receptor.

    This process could be repeated for the other 212 assays by either iterating through them individually or, where a sufficiently small number of assays are returned, using the __in filter on the activity end point to retrieve several assays at once e.g.,,CHEMBL1909156,CHEMBL882906,CHEMBL691450

    An additional 2 assays are identified in this way, reporting an IC50 value of 290nM and a Ki value of 414nM. These values could be averaged, or the lowest taken, to give an indication of the average potency of the compound, or the assay conditions could be investigated further to try to identify which assay might be most reliable or informative (the ChEMBL identifier for the document from which the data are extracted is also provided by the activity end point).

Cheminformatic Utils Web Services

In addition to the described data-focused web services, a utility web service that provides RESTful access to commonly used cheminformatic methods has been released. These web services have been developed under the name 'ChEMBL Beaker' and provide users with access chemical property calculators (e.g. molecular weight), structure format converters (e.g. molfile to SMILES) and a structure standardiser. The methods being exposed by this service are providing RESTful interface to the RDKit cheminformatics library. These services also provide access to methods that extract chemical information from images. The OSRA library is used to expose this functionality. Online documentation is available is available.