UNICHEM
UniChem
spacer

RESTful Web Service API.

Using the UniChem web service API users can retrieve data from the UniChem database in a programmatic fashion. This page documents the currently supported functionality and defines the expected inputs and outputs of each method, together with examples for each one (which may be tested most simply by pasting into a browser, or using an open source tool such as RESTClient from WizTools ). Please note that although that wherever possible small data sets are used in the examples, occassionally the only examples possible are with larger sets, which may take some time to retrieve (such as the auxiliary mapping method). In order to help you get started, we have provided example Perl clients (below). Note that for small, ad hoc queries, users should consider simply using the main interface.

For whole source mapping, users may wish to use the 'download' option on the whole source mapping page instead, which is likely to retrieve data more quickly than the 'get mapping' web services method described below, as the gzipped download files for most source-to-source mapping permutations have been pre-generated and cached.


Constructing Queries.



All RESTful queries are constructed using the following 'stem' or 'base' url...

   https://www.ebi.ac.uk/unichem/rest/   

Specific query urls are all constructed by adding a method name to this base url, followed by input data, as shown in the API methods section below.

Input data may consist of three types...

    src_compound_id
    src_id
    InChIKey

src_id's are integers that represent the various sources in UniChem. A list of valid src_id's can be found either on the sources page or by using the 'Get all src_ids' method below.' For some methods, a 'to_src_id' may be required. This is simply a normal src_id but serves to specify the source to which the output is specifically mapped to.

src_compound_id's are the individual compound identifiers provided by each of the sources. Since src_compound_ids may be ambiguous across different sources, API methods requiring a src_compound_id as an input also require the specification of a corresponding src_id. Note also that src-compound_ids are treated in a case-sensitive manner throughout UniChem (see here for formatting information on search terms).


Content Negotiation.

The default data serialization method is JSON. However, alternative content types are available (eg: YAML, XML, JSONP, etc), but must be selected by the user by specifying the content type HTTP Accept header (eg: 'text/x-yaml', 'text/xml', 'text/javascript', respectively). Note that to return JSONP '?callback=xyz' must be appended to the request_url, where 'xyz' is defined by the user. The returned object will then have the form of... xyz(serializedJSON).


Error Codes.



HTTP Response Code Summary Description
200 OK The request to the web service completed successfully. This includes valid requests that happen to return empty data sets.
400 Bad Request The parameters passed to the API endpoint were deemed invalid. This response will be returned for... 1. Invalid API method names, or 2. Valid method names with invalid numbers of parameters, or 3. InChIKeys which do not match the pattern of a Standard InChIKey version 1
404 Not Found The resource corresponding to the supplied parameters does not exist. This response will be returned if the inputted data type (src_compound_id, src_id, or InChIKey matching the pattern of a Standard InChIKey version 1) does not exist in UniChem.
500 Service Unavailable An internal problem prevented us from fulfilling your request.



Methods.



  1. Get src_compound_ids from src_compound_id
  2. Get src_compound_ids all from src_compound_id
  3. Get mapping
  4. Get src_compound_ids from InChIKey
  5. Get src_compound_ids all from InChIKey
  6. Get all src_ids
  7. Get source infomation
  8. Get structure
  9. Get structure all
  10. Get URL for src_compound_ids from src_compound_id
  11. Get src_compound_ids all from obsolete src_compound_id
  12. Get verbose src_compound_ids from InChIKey
  13. Get auxiliary mappings

Name:  Get src_compound_ids from src_compound_id
Description:  Obtain a list of all src_compound_ids from all sources which are CURRENTLY assigned to the same structure as a currently assigned query src_compound_id. The output will include query src_compound_id if it is a valid src_compound_id with a current assignment. Note also, that by adding an additional (optional) argument (a valid src_id), then results will be restricted to only the source specified with this optional argument.
Extension of base url:  src_compound_id
Number of required input parameters:  2 or 3
Input:  /src_compound_id/src_id(/to_src_id)
Output:  list of two element arrays, containing 'src_compound_id' and 'src_id', or (if optional 'to_src_id' is specified) list of 'src_compound_id's.
Example:  https://www.ebi.ac.uk/unichem/rest/src_compound_id/CHEMBL12/1
Example:  https://www.ebi.ac.uk/unichem/rest/src_compound_id/CHEMBL12/1/2

Name:  Get src_compound_ids all from src_compound_id
Description:  Obtain a list of all src_compound_ids from all sources (including BOTH current AND obsolete assignments) to the same structure as a currently assigned query src_compound_id. The output will include query src_compound_id if it is a valid src_compound_id with a current assignment. Note also, that by adding an additional (optional) argument (a valid src_id), then results will be restricted to only the source specified with this optional argument.
Extension of base url:  src_compound_id_all
Number of required input parameters:  2 or 3
Input:  /src_compound_id/src_id(/to_src_id)
Output:  list of three element arrays, containing 'src_compound_id', 'src_id' and 'Assignment', or (if optional 'to_src_id' is specified) list of two element arrays, containing 'src_compound_id' and 'Assignment'.
Example:  https://www.ebi.ac.uk/unichem/rest/src_compound_id_all/CHEMBL12/1
Example:  https://www.ebi.ac.uk/unichem/rest/src_compound_id_all/CHEMBL12/1/2

Name:  Get mapping
Description:  Obtain a full mapping between two sources. Uses only currently assigned src_compound_ids from both sources.
Extension of base url:  mapping
Number of required input parameters:  2
Input:  src_id/to_src_id
Output:  list of two element arrays, containing 'src_compound_id' and 'src_compound_id'.
Example:  https://www.ebi.ac.uk/unichem/rest/mapping/4/1

Name:  Get src_compound_ids from InChIKey
Description:  Obtain a list of all src_compound_ids (from all sources) which are CURRENTLY assigned to a query InChIKey
Extension of base url:  inchikey
Number of required input parameters:  1
Input:  /InChIKey
Output:  list of two element arrays, containing 'src_compound_id' and 'src_id'.
Example:  https://www.ebi.ac.uk/unichem/rest/inchikey/AAOVKJBEBIDNHE-UHFFFAOYSA-N

Name:  Get src_compound_ids all from InChIKey
Description:  Obtain a list of all src_compound_ids (from all sources) which have current AND obsolete assignments to a query InChIKey
Extension of base url:  inchikey_all
Number of required input parameters:  1
Input:  /InChIKey
Output:  list of two element arrays, containing 'src_compound_id', 'src_id' and 'Assignment'.
Example:  https://www.ebi.ac.uk/unichem/rest/inchikey_all/AAOVKJBEBIDNHE-UHFFFAOYSA-N

Name:  Get all src_ids
Description:  Obtain all src_ids currently in UniChem
Extension of base url:  src_ids
Number of required input parameters:  0
Input:   - none -
Output:  list of 'src_id's.
Example:  https://www.ebi.ac.uk/unichem/rest/src_ids/

Name:  Get source infomation
Description:  Obtain all information on a source by querying with a source id (src_id).
Extension of base url:  sources
Number of required input parameters:  1
Input:  /src_id
Output:  list containing:
src_id (the src_id for this source),
src_url (the main home page of the source),
name (the unique name for the source in UniChem, always lower case),
name_long (the full name of the source, as defined by the source),
name_label (A name for the source suitable for use as a 'label' for the source within a web-page. Correct case setting for source, and always less than 30 characters),
description (a description of the content of the source),
base_id_url_available (an flag indicating whether this source provides a valid base_id_url for creating cpd-specific links [1=yes, 0=no]).
base_id_url (the base url for constructing hyperlinks to this source [append an identifier from this source to the end of this url to create a valid url to a specific page for this cpd], unless aux_for_url=1),
aux_for_url (A flag to indicate whether the aux_src field should be used to create hyperlinks instead of the src_compound_id [1=yes, 0=no]
Example:  https://www.ebi.ac.uk/unichem/rest/sources/1

Name:  Get structure
Description:  Obtain structure(s) CURRENTLY assigned to a query src_compound_id.
Extension of base url:  structure
Number of required input parameters:  2
Input:  /src_compound_id/src_id
Output:  list of two element arrays, containing 'Standard InChI', and 'Standard InChIKey'
Example:  https://www.ebi.ac.uk/unichem/rest/structure/CHEMBL12/1

Name:  Get structure all
Description:  Obtain structure(s) with current AND obsolete assignments to a query src_compound_id.
Extension of base url:  structure_all
Number of required input parameters:  2
Input:  /src_compound_id/src_id
Output:  list of three element arrays, containing 'Standard InChI', 'Standard InChIKey', and 'Assignment'
Example:  https://www.ebi.ac.uk/unichem/rest/structure_all/CHEMBL12/1

Name:  Get URL for src_compound_ids from src_compound_id
Description:  Obtain a list of URLs for all src_compound_ids, from a specified source (the 'to_src_id'), which are CURRENTLY assigned to the same structure as a currently assigned query src_compound_id. Method only applicable for sources which support direct URLs to src_compound_id pages. Method also applicable for 'to_src_id's where the hyperlink is constructed from auxiliary data [and not from the src_compound_id] as per example2 below.
Extension of base url:  src_compound_id_url
Number of required input parameters:  3
Input:  /src_compound_id/src_id/to_src_id
Output:  list of URLs.
Example:  https://www.ebi.ac.uk/unichem/rest/src_compound_id_url/CHEMBL12/1/2
Example:  https://www.ebi.ac.uk/unichem/rest/src_compound_id_url/CHEMBL490/1/15

Name:  Get src_compound_ids all from obsolete src_compound_id
Description:  Obtain a list of all src_compound_ids from all sources with BOTH current AND obsolete to the same structure with an obsolete assignment to the query src_compound_id. The output will include query src_compound_id if it is a valid src_compound_id with an obsolete assignment. Note also, that by adding an additional (optional) argument (a valid src_id), then results will be restricted to only the source specified with this optional argument.
Extension of base url:  src_compound_id_all_obsolete
Number of required input parameters:  2 or 3
Input:  /src_compound_id/src_id(/to_src_id)
Output:  list of four element arrays, containing 'src_compound_id', 'src_id', 'Assignment' and 'InChIKey', or (if optional 'to_src_id' is specified) list of three element arrays, containing 'src_compound_id', 'Assignment' and 'UCI'.
Example:  https://www.ebi.ac.uk/unichem/rest/src_compound_id_all_obsolete/DB07699/2
Example:  https://www.ebi.ac.uk/unichem/rest/src_compound_id_all_obsolete/DB07699/2/1

Name:  Get verbose src_compound_ids from InChIKey
Description:  Obtain all src_compound_ids (from all sources) which are CURRENTLY assigned to a query InChIKey. However, these are returned as part of the following data structure: A list of sources containing these src_compound_ids, including source description, base_id_url, etc. One element in this list is a list of the src_compound_ids currently assigned to the query InChIKey.
Extension of base url:  verbose_inchikey
Number of required input parameters:  1
Input:  /InChIKey
Output:  list containing:
src_id (the src_id for this source),
src_url (the main home page of the source),
name (the unique name for the source in UniChem, always lower case),
name_long (the full name of the source, as defined by the source),
name_label (A name for the source suitable for use as a 'label' for the source within a web-page. Correct case setting for source, and always less than 30 characters),
description (a description of the content of the source),
base_id_url_available (an flag indicating whether this source provides a valid base_id_url for creating cpd-specific links [1=yes, 0=no]).
base_id_url (the base url for constructing hyperlinks to this source [append an identifier from this source to the end of this url to create a valid url to a specific page for this cpd], unless aux_for_url=1),
aux_for_url (A flag to indicate whether the aux_src field should be used to create hyperlinks instead of the src_compound_id [1=yes, 0=no] ,
src_compound_id (a list of src_compound_ids from this source which are currently assigned to the query InChIKey.
aux_src (a list of src-compound_id keys mapping to corresponding auxiliary data (url_id:value), for creating links if aux_for_url=1. Only shown if aux_for_url=1).
Example:  https://www.ebi.ac.uk/unichem/rest/verbose_inchikey/GZUITABIAKMVPG-UHFFFAOYSA-N

Name:  Get auxiliary mappings
Description:  For a single source, obtain a mapping between all current src_compound_ids to their corresponding auxiliary data. See FAQ for an explanation of 'auxiliary data'. Please note that the only examples available (below) for this method may be very large data sets, and may therefore take a very long time to retrieve. A much faster method of retrieving this same data set is to download the pre-cached, gzipped mapping file for the source of interest from the Auxiliary Data Mapping page.
Extension of base url:  mappingaux
Number of required input parameters:  1
Input:  /src_id
Output:  list of two element arrays, containing 'src_compound_id' and 'auxiliary data'.
Example:  https://www.ebi.ac.uk/unichem/rest/mappingaux/20


Example perl client



The example perl script below illustrate how the web services may be queried programmatically. By uncommenting different lines, different queries may be run. The default media type / serialization method for these services is JSON, but note that others may be used by explicitly defining the request's accept header (uncomment options below).


Example


The perl script below utilizes the REST::Client module


    
    #!/usr/bin/perl
    use strict;
    use warnings;
    use Data::Dumper;
    use REST::Client;
    
    my $baseURL = "https://www.ebi.ac.uk/unichem/rest";
    my $addMe = ""; # ...append to request_url if callback required (for JSONP)
    ## -----------------------------------
    ## create client...
    my $client = REST::Client->new();
    ## -----------------------------------
    ## select the appropriate 'Accept' header, if alternative to default required.... (json is default if none chosen)
    #$client->addHeader( content_type => 'text/html' );
    #$client->addHeader( content_type => 'text/xml' );
    #$client->addHeader( content_type => 'text/x-yaml' );
    #$client->addHeader( content_type => 'application/json' );
    #$client->addHeader( content_type => 'text/x-json' );
    #$client->addHeader( content_type => 'text/x-data-dumper' );
    $client->addHeader( content_type => 'text/javascript' ); $addMe = "?callback=parseMe";   # for JSONP
    ## -----------------------------------
    ## select query (uncomment one of these)...
    #my $request_url =  "$baseURL/src_compound_id/CHEMBL12/1$addMe";
    #my $request_url =  "$baseURL/src_compound_id_all/CHEMBL505348/1$addMe";
    #my $request_url =  "$baseURL/mapping/1/6$addMe";
    #my $request_url =  "$baseURL/structure/196322$addMe";
    #my $request_url =  "$baseURL/sources/1$addMe";
    #my $request_url =  "$baseURL/inchikey/HNHCIVXQBMBKPQ-ARMUENPQSA-N$addMe";
    #my $request_url =  "$baseURL/inchikey_all/HNHCIVXQBMBKPQ-ARMUENPQSA-N$addMe";
    my $request_url =  "$baseURL/verbose_inchikey/HAUGRYOERYOXHX-UHFFFAOYSA-N$addMe";
    ## -----------------------------------
    ## get the data...
    $client->GET($request_url);
    ## -----------------------------------
    ## process the retrieved data...
    my $data = $client->responseContent();
    ## -----------------------------------
    ## print...
    print Dumper($data);
    
    __END__
    
    
    
    
    }

Back to UniChem Home and Query page.

BMB EU-OPENSCREEN
spacer
spacer