The main aim of ChEBI Web Services is to provide programmatic access to the ChEBI database in order to aid our users in integrating ChEBI into their applications. Web Services is an integration technology. To ensure software from various sources work well together, this technology is built on open standards such as Simple Object Access Protocol (SOAP), a messaging protocol for transporting information, Web Services Description Language (WSDL), a standard method of describing Web Services and their capabilities. For the transport layer itself, Web Services utilise most of the commonly available network protocols, especially Hypertext Transfer Protocol (HTTP).
ChEBI provides SOAP access to its database. If you just wish to obtain light weight ontology objects you can use the Ontology Lookup Service as alternative Web Services.
The ChEBI WSDL specifies the contract between external developers and the ChEBI Web Services. The Web Service Description Language (WSDL) is an XML format for describing network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information.
The ChEBI WSDL uses the Document/literal binding. A WSDL binding describes how the service is bound to a messaging protocol, particularly the SOAP messaging protocol.
The ChEBI Web Services contains four main operations with which developers can access data. An example invocation of the SOAP response can be seen by filling in the forms and submitting them. These forms are only for demonstration purposes and should not be used for any production purposes.
The JavaDoc for the ChEBI model used for the data can be accessed online.
Retrieves a list of "lite" entities containing only the ChEBI ASCII name and ChEBI identifier. The input parameters are a search string and a search category. If the search category is null then it will search under all fields. The search string accepts the wildcard character "*" and also unicode characters. You can get maximum results upto 5000 entries at a time.
Retrieves the complete entity including synonyms, database links and chemical structures, using the ChEBI identifier.
This method returns the UpdatedPolymer object containing the updated 2D MolFile structure, GlobalFormula string containing the formulae for each repeating-unit, the GlobalCharge string containing the charge on individual repeating-units and the primary ChEBI ID of the polymer, even if the secondary Identifier was passed to the web-service.
Given a list of ChEBI accession numbers, retrieve the complete Entities. The maximum size of this list is 50. In this example we will use a list of two accessions.
Retrieves the ontology parents of an entity including the relationship type, using the ChEBI identifier.
Retrieves the ontology children of an entity including the relationship type, using the ChEBI identifier.
Retrieves the ontology children of an entity including the relationship type, using the ChEBI identifier.
Does a substructure, similarity or identity search using a structure.
The ChEBI Web Services team has provided the clients in perl and Java to access data. If you want a more specific client please follow the tutorial on the EBI Web Services page.
These are accessible on the ChEBI Web Services clients page with four main files to download depending on the methods you would like to access. The clients were tested with SOAP::Lite version 0.67.
Below is an example perl file accessing the getCompleteEntity method.
#!/usr/bin/perl -w
# SOAP::Lite version 0.67
# Please note: ChEBI webservices uses document/literal binding
use SOAP::Lite + trace => qw(debug);
#use SOAP::Lite;
# Setup service
my $WSDL = 'https://www.ebi.ac.uk/webservices/chebi/2.0/webservice?wsdl';
my $nameSpace = 'https://www.ebi.ac.uk/webservices/chebi';
my $soap = SOAP::Lite
-> uri($nameSpace)
-> proxy($WSDL);
# Setup method and parameters
my $method = SOAP::Data->name('getCompleteEntity')
->attr({xmlns => $nameSpace});
my @params = ( SOAP::Data->name(chebiId => 'CHEBI:15377'));
# Call method
my $som = $soap->call($method => @params);
# Retrieve for example all ChEBI identifiers for the ontology parents
@stuff = $som->valueof('//OntologyParents//chebiId');
print @stuff;
The Java client was generated using Java API for XML Web Services
(JAX-WS) version 2.0. Java version 1.5+ is required to run the client.
To run this client you should download the chebiWS-client-2.4.jar file
and place it in your classpath. In addition you should download a
recent version of JAX-WS and put
its libraries in your classpath. The ChebiWebServiceClient object is automatically instantiated
with a value that describes the location of the ChEBI Web Services WSDL and ChEBI namespace.
At this moment these are located as follows:
ChEBI WSDL: https://www.ebi.ac.uk/webservices/chebi/2.0/webservice?wsdl
ChEBI namespace (QName) is: https://www.ebi.ac.uk/webservices/chebi
The JavaDoc and JAX-WS generated Java client for the ChEBI model used for the data can be accessed online. In the WSChebiJAX-WS.jar file an Example.java class can be found with an example code. An example is provided for each method below.
import uk.ac.ebi.chebi.webapps.chebiWS.client.ChebiWebServiceClient;
import uk.ac.ebi.chebi.webapps.chebiWS.model.ChebiWebServiceFault_Exception;
import uk.ac.ebi.chebi.webapps.chebiWS.model.*;
public class Example {
//=======getLiteEntity===========//
public static void getLiteEntityExample (){
try {
ChebiWebServiceClient client = new ChebiWebServiceClient(); // Create client
System.out.println("Invoking getLiteEntity");
LiteEntityList entities = client.getLiteEntity("alpha*",
SearchCategory.ALL,
50,
StarsCategory.ALL);
List<LiteEntity> resultList = entities.getListElement();
for ( LiteEntity liteEntity : resultList ) {
System.out.println("CHEBI ID: " + liteEntity.getChebiId());
}
} catch ( ChebiWebServiceFault_Exception e ) {
System.err.println(e.getMessage());
}
}
//=======getCompleteEntity===========//
public static void getCompleteEntityExample (){
try {
// Create client
ChebiWebServiceClient client = new ChebiWebServiceClient();
System.out.println("Invoking getCompleteEntity");
Entity entity = client.getCompleteEntity("CHEBI:15377");
System.out.println("GetName: " + entity.getChebiAsciiName());
List<DataItem> synonyms = entity.getSynonyms();
for ( DataItem dataItem : synonyms ) { // List all synonyms
System.out.println("synonyms: " + dataItem.getData());
}
} catch ( ChebiWebServiceFault_Exception e ) {
System.err.println(e.getMessage());
}
}
//=======getCompleteEntityByList===========//
public static void getCompleteEntityByListExample() {
try {
// Create client
ChebiWebServiceClient client = new ChebiWebServiceClient();
System.out.println("Invoking getCompleteEntityByList");
List<String> list = new ArrayList<String>();
list.add("15377");
list.add("101090");
//List all entities
List<Entity> resultList = client.getCompleteEntityByList(list);
for (Entity entity : resultList) {
System.out.println("CHEBI ID: " + entity.getChebiId());
}
} catch (ChebiWebServiceFault_Exception e) {
System.err.println(e.getMessage());
}
}
//=======getOntologyParents===========//
public static void getOntologyParentsExample() {
try {
// Create client
ChebiWebServiceClient client = new ChebiWebServiceClient();
System.out.println("Invoking getOntologyParents");
OntologyDataItemList parents = client.getOntologyParents("CHEBI:15377");
List <OntologyDataItem & gt; parentList = parents.getListElement();
//List all parents
for (OntologyDataItem ontologyDataItem : parentList) {
System.out.println("CHEBI names: " + ontologyDataItem.getChebiName());
}
} catch (ChebiWebServiceFault_Exception e) {
System.err.println(e.getMessage());
}
}
//=======getOntologyChildren===========//
public static void getOntologyChildrenExample() {
try {
// Create client
ChebiWebServiceClient client = new ChebiWebServiceClient();
System.out.println("Invoking getOntologyChildren");
OntologyDataItemList children = client.getOntologyChildren("CHEBI:15377");
List <OntologyDataItem > childrenList = children.getListElement();
//List all children
for (OntologyDataItem ontologyDataItem : childrenList) {
System.out.println("CHEBI ID: " + ontologyDataItem.getChebiId());
}
} catch (ChebiWebServiceFault_Exception e) {
System.err.println(e.getMessage());
}
}
//=======getAllOntologyChildrenInPath===========//
public static void getAllOntologyChildrenInPathExample (){
try {
// Create client
ChebiWebServiceClient client = new ChebiWebServiceClient();
System.out.println("Invoking getAllOntologyChildrenInPath");
LiteEntityList entities = client.getAllOntologyChildrenInPath("15377",
RelationshipType.IS_A,
false);
List<LiteEntity> resultList = entities.getListElement();
//List all children entities
for ( LiteEntity liteEntity : resultList ) {
System.out.println("CHEBI ID: " + liteEntity.getChebiId());
}
} catch ( ChebiWebServiceFault_Exception e ) {
System.err.println(e.getMessage());
}
}
//=======getStructureSearch===========//
public static void getStructureSearchExample() {
try {
// Create client
ChebiWebServiceClient client = new ChebiWebServiceClient();
System.out.println("Invoking getStructureSearch");
// String mol file
String water = "\n" +
" Marvin 02220718252D \n" +
"\n" +
" 3 2 0 0 0 0 999 V2000\n" +
" -0.4125 0.7145 0.0000 H 0 0 0 0 0 0 0 0 0 0 0 0\n" +
" 0.0000 0.0000 0.0000 O 0 0 0 0 0 0 0 0 0 0 0 0\n" +
" -0.4125 -0.7145 0.0000 H 0 0 0 0 0 0 0 0 0 0 0 0\n" +
" 2 1 1 0 0 0 0\n" +
" 2 3 1 0 0 0 0\n" +
"M END";
LiteEntityList entities = client.getStructureSearch(water,
StructureType.MOLFILE,
StructureSearchCategory.SIMILARITY,
50,
0.70F);
for (LiteEntity liteEntity : entities.getListElement()) {
System.out.println("CHEBI ID: " + liteEntity.getChebiId());
}
} catch (ChebiWebServiceFault_Exception e) {
System.err.println(e.getMessage());
}
}
}
Here are some examples emailed in by users illustrating how you can use the ChEBI Web Service.
How do I extract all functional groups in ChEBI?
All functional groups in ChEBI are suffixed with the term group. There chemical structures use the asterisk to represent where the structure connects.
Therefore they do not have an InChI or SMILES associated with them. In addition all groups in ChEBI have an eventual is_a relationship to the
term groups (CHEBI:24433).
There are multiple ways to approach this problem. Two are described below.
What you should do is first search for all terms containing the word 'group':
https://www.ebi.ac.uk/webservices/chebi/2.0/test/getLiteEntity?search=group&searchCategory=CHEBI+NAME&maximumResults=200&starsCategory=ALL
Then for each term you should extract the complete entity and check if there is a structure associated.
For example, L-tyorosino group has a chemical structure because there is a molfile:
https://www.ebi.ac.uk/webservices/chebi/2.0/test/getCompleteEntity?chebiId=46857
This filtering will ensure that you get only functional groups. Below is the Perl code for method 1.
#!/usr/bin/perl -w
# SOAP::Lite version 0.67
# Please note: ChEBI webservices uses document/literal binding
# This little program extracts all functional groups and prints
# them out. It searches for the word group in the ChEBI name and
# then discards any results which do not have chemical structures.
#use SOAP::Lite + trace => qw(debug);
use SOAP::Lite;
# Setup service
my $WSDL = 'https://www.ebi.ac.uk/webservices/chebi/2.0/webservice?wsdl';
my $nameSpace = 'https://www.ebi.ac.uk/webservices/chebi';
my $soap = SOAP::Lite
-> uri($nameSpace)
-> proxy($WSDL);
# Setup getLiteEntity for searching
my $method = SOAP::Data->name('getLiteEntity')
->attr({xmlns => $nameSpace});
# Setup full method to later retrieve chemical structures
my $fullMethod = SOAP::Data->name('getCompleteEntity')
->attr({xmlns => $nameSpace});
# Setup parameters to search for group
my @params = ( SOAP::Data->name(search => 'group'),
SOAP::Data->name(searchCategory => 'CHEBI NAME'));
# Call getLiteEntity method
my $som = $soap->call($method => @params);
# Retrieve all the ChEBI identifiers to iterate through them
# and check the structures
@ids = $som->valueof('//ListElement//chebiId');
my $counter = 0;
foreach $var (@ids) {
# Setup params based on ChEBI id of array to retrieve
# the full entry
my @fullParams = ( SOAP::Data->name(chebiId => $var));
my $full = $soap->call($fullMethod => @fullParams);
# Extract any ChemicalStructures in the result
@strucs = $full->valueof('//ChemicalStructures//structure');
# Discard any chemical structures not present
# and print the ones which are
if ($#strucs!=-1) {
$counter++;
print "$var is a functional group\n";
}
}
# print the number of functional groups found.
print "$counter functional groups found \n";
Use the ChEBI ontology and navigate down the ontology tree using the groups (CHEBI:24433) as the main entry point.
Use the method getOntologyChildren to get all children of the term:
http://www.ebi.ac.uk/webservices/chebi/2.0/test/getOntologyChildren?chebiId=24433
Navigate down the tree extracting only 'is a' relationships and terms ending in 'group'. For example,
the next 'is a' relationship down from groups is 'inorganic groups' (CHEBI:33246) and here you see a list of valid group terms:
http://www.ebi.ac.uk/webservices/chebi/2.0/test/getOntologyChildren?chebiId=33246
For each group extracted check to see whether a chemical structure exists. For example, lambda(5)-arsanyl group (CHEBI:30273):
http://www.ebi.ac.uk/webservices/chebi/2.0/test/getCompleteEntity?chebiId=30273
The current version of the ChEBI Web Services is Version 2.4. You can subscribe to all version
announcements using the RSS feeds.
All changes and new releases to the ChEBI Services will be announced on the ChEBI RSS Feed. Please subscribe by copying the link into your RSS Reader.
For more information on RSS feeds see our help file.
If the methods provided are not adequate for your applications please submit a request for the desired method on our Contact page or GitHub. We are happy consider each request and extend the ChEBI Web Services as users see fit.