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.
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 | https://www.ebi.ac.uk/chembl/api/data/activity |
| Assay | Assay details as reported in source Document/Dataset | https://www.ebi.ac.uk/chembl/api/data/assay |
| ATC | WHO ATC Classification for drugs | https://www.ebi.ac.uk/chembl/api/data/atc_class |
| Binding Site | Target binding site definition | https://www.ebi.ac.uk/chembl/api/data/binding_site |
| Biotherapeutic | Biotherapeutic molecules, which includes HELM notation and sequence data | https://www.ebi.ac.uk/chembl/api/data/biotherapeutic |
| Cell Line | Cell line information | https://www.ebi.ac.uk/chembl/api/data/cell_line |
| ChEMBL ID Lookup | Look up ChEMBL Id entity type | https://www.ebi.ac.uk/chembl/api/data/chembl_id_lookup |
| Compound Record | Occurence of a given compound in a specific document | https://www.ebi.ac.uk/chembl/api/data/compound_record |
| Compound Structural Alert | Indicates certain anomaly in compound structure | https://www.ebi.ac.uk/chembl/api/data/compound_structural_alert |
| Document | Document/Dataset from which Assays have been extracted | https://www.ebi.ac.uk/chembl/api/data/document |
| Document Similarity | Provides documents similar to a given one | https://www.ebi.ac.uk/chembl/api/data/document_similarity |
| Document Term | Provides keywords extracted from a document using the TextRank algorithm | https://www.ebi.ac.uk/chembl/api/data/document_term |
| Drug | Approved drugs information, including (but not limited to) applicants, patent numbers and research codes. This endpoint aggregates data on the parent, please use the parent chembl id found in other endpoints | https://www.ebi.ac.uk/chembl/api/data/drug |
| Drug Indication | Joins drugs with diseases providing references to relevant sources | https://www.ebi.ac.uk/chembl/api/data/drug_indication |
| Drug Warning | Safety information for drugs withdrawn from one or more regions of the world and drugs that carry a warning for severe or life threatening adverse effects | https://www.ebi.ac.uk/chembl/api/data/drug_warning |
| GO Slim | GO slim ontology | https://www.ebi.ac.uk/chembl/api/data/go_slim |
| Image | Graphical (svg) representation of Molecule | https://www.ebi.ac.uk/chembl/api/data/image/CHEMBL1 |
| Mechanism | Mechanism of action information for approved drugs | https://www.ebi.ac.uk/chembl/api/data/mechanism |
| Metabolism | Metabolic pathways with references | https://www.ebi.ac.uk/chembl/api/data/metabolism |
| Molecule | Molecule information, including properties, structural representations and synonyms | https://www.ebi.ac.uk/chembl/api/data/molecule |
| Molecule Form | Relationships between molecule parents and salts | https://www.ebi.ac.uk/chembl/api/data/molecule_form |
| Organism | Simple organism classification | https://www.ebi.ac.uk/chembl/api/data/organism |
| Protein Classification | Protein family classification of TargetComponents | https://www.ebi.ac.uk/chembl/api/data/protein_classification |
| Similarity | Molecule similarity search | https://www.ebi.ac.uk/chembl/api/data/similarity/CC%28=O%29Oc1ccccc1C%28=O%29O/70 |
| Source | Document/Dataset source | https://www.ebi.ac.uk/chembl/api/data/source |
| Status | API status with ChEMBL DB version number and API software version number | https://www.ebi.ac.uk/chembl/api/data/status |
| Substructure | Molecule substructure search | https://www.ebi.ac.uk/chembl/api/data/substructure/CN%28CCCN%29c1cccc2ccccc12 |
| Target | Targets (protein and non-protein) defined in Assay | https://www.ebi.ac.uk/chembl/api/data/target |
| Target Component | Target sequence information (a Target may have 1 or more sequences) | https://www.ebi.ac.uk/chembl/api/data/target_component |
| Target Relation | Describes relations between targets | https://www.ebi.ac.uk/chembl/api/data/target_relation |
| Tissue | Tissue classification | https://www.ebi.ac.uk/chembl/api/data/tissue |
| X-Ref (Cross references) | Cross references to other resources for compounds | https://www.ebi.ac.uk/chembl/api/data/xref_source |
These are formats currently supported by the API:
NOTE: if both the extension and the format parameter are specified, the format parameter will take precedence
For example this request https://www.ebi.ac.uk/chembl/api/data/molecule.yaml?format=json will return a JSON document
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: https://www.ebi.ac.uk/chembl/api/data/activity. By inspecting the the 'page_meta' section the link to page 2 can be found, e.g. https://www.ebi.ac.uk/chembl/api/data/activity?limit=20&offset=20.
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: https://www.ebi.ac.uk/chembl/api/data/target?pref_name__contains=kinase.
The pattern for applying a filter is as follows:
https://www.ebi.ac.uk/chembl/api/data/[resource]?[field]__[filter_type]=[value]
Examples of other filter type are listed in the table below.\
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: https://www.ebi.ac.uk/chembl/api/data/target?order_by=pref_name
The default ordering is in ascending order. To return the results in descending orede place a '-' before the field name: https://www.ebi.ac.uk/chembl/api/data/target?order_by=-pref_name
Note that it is possible combine order_by and filter arguments:https://www.ebi.ac.uk/chembl/api/data/target?pref_name__contains=kinase&order_by=-pref_name\
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 | https://www.ebi.ac.uk/chembl/api/data/substructure/CC(=O)Oc1ccccc1C(=O)O |
| Substructure search for against ChEMBL using aspirin CHEMBL_ID | https://www.ebi.ac.uk/chembl/api/data/substructure/CHEMBL25 |
| Substructure search for against ChEMBL using aspirin InChI Key | https://www.ebi.ac.uk/chembl/api/data/substructure/BSYNRYMUTXBXSQ-UHFFFAOYSA-N |
| Similarity (80% cut off) search for against ChEMBL using aspirin SMILES string | https://www.ebi.ac.uk/chembl/api/data/similarity/CC(=O)Oc1ccccc1C(=O)O/80 |
| Similarity (80% cut off) search for against ChEMBL using aspirin CHEMBL_ID | https://www.ebi.ac.uk/chembl/api/data/similarity/CHEMBL25/80 |
| Similarity (80% cut off) search for against ChEMBL using aspirin InChI Key | https://www.ebi.ac.uk/chembl/api/data/similarity/BSYNRYMUTXBXSQ-UHFFFAOYSA-N/80 |
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.\
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 accept image specific arguments. These are defined in the table below.\
| Image Argument | Description | Allowed Values | Default Value | Example URL |
|---|---|---|---|---|
| format | Image format | svg | svg | https://www.ebi.ac.uk/chembl/api/data/image/CHEMBL25?format=svg |
| dimensions | Size of image in pixels | 1-500 | 500 | https://www.ebi.ac.uk/chembl/api/data/image/CHEMBL25?dimensions=200 |
| ignoreCoords | Choose to use or ignore coordinates in ChEMBL molfiles | 1 or 0 | 0 (Use ChEMBL molfile coordinates) | https://www.ebi.ac.uk/chembl/api/data/image/CHEMBL25?ignoreCoords=1 |
In GET request all the parameters has to be encoded into URL. Because there is a limitation of how long a URL can be it's often more convenient to use POST requests instead. POST parameters are embedded into request body and can be of any size. This is especially important when retrieving a long list of entities identified by (random) IDs.
ChEMBL API supports both GET and POST but since POST has a special meaning in REST protocol (CREATE), a special header has to be added to every POST request:
X-HTTP-Method-Override:GET
Another issue is character encoding. SMILES strings often contain characters (such as #, % or \) that have a special meaning in URLs. This is why when using GET, all parameters should be percent-encoded.
One example is a following SMILES string:
[Na+].CO[C@@H](CCC#C\C=C/CCCC(C)CCCCC=C)C(=O)[O-]
Which can be encoded into URL in a following way: https://www.ebi.ac.uk/chembl/api/data/molecule/%5BNa+%5D.CO%5BC@@H%5D(CCC%23C%5CC=C/CCCC(C)CCCCC=C)C(=O)%5BO-%5D
Below is another example of retrieving a molecule (CHEMBL1628285) that has the longest SMILES string currently stored in ChEMBL. The original SMILES string is:
CCCCCCCCCCCCCCCC[NH2+]OC(CO)C(O)C(OC1OC(CO)C(O)C(O)C1O)C(O)CO.CCCCCCCCCCCCCCCC[NH2+]OC(CO)C(O)C(OC2OC(CO)C(O)C(O)C2O)C(O)CO.CCCCCCCCCCCCCCCC[NH2+]OC(CO)C(O)C(OC3OC(CO)C(O)C(O)C3O)C(O)CO.CCCCCCCCCCCCCCCC[NH2+]OC(CO)C(O)C(OC4OC(CO)C(O)C(O)C4O)C(O)CO.CCCCCCCCCCCCCCCC[NH2+]OC(CO)C(O)C(OC5OC(CO)C(O)C(O)C5O)C(O)CO.CCCCCCCCCCCCCCCC[NH2+]OC(CO)C(O)C(OC6OC(CO)C(O)C(O)C6O)C(O)CO.CCCCCCCCCCCCCCCC[NH2+]OC(CO)C(O)C(OC7OC(CO)C(O)C(O)C7O)C(O)CO.CCCCCCCCCCCCCCCC[NH2+]OC(CO)C(O)C(OC8OC(CO)C(O)C(O)C8O)C(O)CO.CCCCCCCCCCCCCCCC[NH2+]OC(CO)C(O)C(OC9OC(CO)C(O)C(O)C9O)C(O)CO.CCCCCCCCCCCCCCCC[NH2+]OC(CO)C(O)C(OC%10OC(CO)C(O)C(O)C%10O)C(O)CO.CCCCCCCCCCCCCCCC[NH2+]OC(CO)C(O)C(OC%11OC(CO)C(O)C(O)C%11O)C(O)CO.CCCCCCCCCCCCCCCC[NH2+]OC(CO)C(O)C(OC%12OC(CO)C(O)C(O)C%12O)C(O)CO.CCCCCCCCCC(C(=O)NCCc%13ccc(OP(=S)(Oc%14ccc(CCNC(=O)C(CCCCCCCCC)P(=O)(O)[O-])cc%14)N(C)\\N=C\\c%15ccc(Op%16(Oc%17ccc(\\C=N\\N(C)P(=S)(Oc%18ccc(CCNC(=O)C(CCCCCCCCC)P(=O)(O)[O-])cc%18)Oc%19ccc(CCNC(=O)C(CCCCCCCCC)P(=O)(O)[O-])cc%19)cc%17)np(Oc%20ccc(\\C=N\\N(C)P(=S)(Oc%21ccc(CCNC(=O)C(CCCCCCCCC)P(=O)(O)[O-])cc%21)Oc%22ccc(CCNC(=O)C(CCCCCCCCC)P(=O)(O)[O-])cc%22)cc%20)(Oc%23ccc(\\C=N\\N(C)P(=S)(Oc%24ccc(CCNC(=O)C(CCCCCCCCC)P(=O)(O)[O-])cc%24)Oc%25ccc(CCNC(=O)C(CCCCCCCCC)P(=O)(O)[O-])cc%25)cc%23)np(Oc%26ccc(\\C=N\\N(C)P(=S)(Oc%27ccc(CCNC(=O)C(CCCCCCCCC)P(=O)(O)[O-])cc%27)Oc%28ccc(CCNC(=O)C(CCCCCCCCC)P(=O)(O)[O-])cc%28)cc%26)(Oc%29ccc(\\C=N\\N(C)P(=S)(Oc%30ccc(CCNC(=O)C(CCCCCCCCC)P(=O)(O)[O-])cc%30)Oc%31ccc(CCNC(=O)C(CCCCCCCCC)P(=O)(O)[O-])cc%31)cc%29)n%16)cc%15)cc%13)P(=O)(O)[O-]
After encoding, the URL becomes this\
You can call our web services directly from JavaScript on your own web application since both techniques are supported.
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 install from Python Package Index by typing:
pip install chembl_webresource_clientThe client code is open and hosted on GitHub: https://github.com/chembl/chembl_webresource_client.
Jupyter notebook with examples available.
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 together to build up more complex workflows.
The following use cases are provided as an example of how it is possible to chain together ChEMBL web service calls to answer to complicated questions using ChEMBL data.
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.
-
Use the molecule end point to retrieve a list of approved drugs (max_phase=4):
https://www.ebi.ac.uk/chembl/api/data/molecule?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. \ -
Use the mechanism end point to retrieve the mechanism of action and target of each drug:
https://www.ebi.ac.uk/chembl/api/data/mechanism?molecule_chembl_id=CHEMBL998
Loratadine is reported to be a histamine H1 receptor antagonist, represented by the ChEMBL target CHEMBL231. \ -
Use the assay end point to identify any binding assays (assay_type=B) for the human histamine H1 receptor:
https://www.ebi.ac.uk/chembl/api/data/assay?target_chembl_id=CHEMBL231&relationship_type=D&assay_type=B
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. \ -
Combine the results of the above queries to identify any potency measurements for loratadine in these assays:
https://www.ebi.ac.uk/chembl/api/data/activity?molecule_chembl_id=CHEMBL998&assay_chembl_id=CHEMBL1909156
This assay reports an IC50 value of 170 nM and a Ki measurement of 20 nM 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.,
https://www.ebi.ac.uk/chembl/api/data/activity?molecule_chembl_id=CHEMBL998&assay_chembl_id__in=CHEMBL830379,CHEMBL1909156,CHEMBL882906,CHEMBL691450
An additional 2 assays are identified in this way, reporting an IC50 value of 290 nM and a Ki value of 414 nM. 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).