Web Service


XML-RPC web services

It is possible to access some of the LRG information programatically via the XML-RPC protocol. This enables methods to be called on a remote server and the result to be returned to the client over HTTP. Parameters and return values are encoded using XML. For detailed instructions on how to communicate via the XML-RPC protocol, please refer to e.g. online tutorials.

The methods exposed by the service can be viewed by calling system.listMethods without any arguments. The method signature and a brief description can be obtained by calling system.methodSignature and system.methodHelp with the name of the method as parameter.

In order to use these web services, you need to first request an authentication key by sending an email to help@lrg-sequence.org. The obtained authentication key must be passed as the first argument to all methods. The URL of the LRG web service is http://www.lrg-sequence.org/xmlrpc.php.

Below is a description of the methods available from the LRG web service (lrg_service.<Method>):

Method

Description Input arguments Return type Example

getCoordinates

Returns the genomic coordinates of the supplied LRG identifiers

<string> Authentication key
<string> LRG id
<string> output format
                 e.g. "text", "json"

<string> in text format "chromosome:start:end:strand"
(if the output format defined as 3rd argument is text)

OR

<string> in JSON format
(if the output format defined as 3rd argument is json)

 Here

getPublic

Returns the LRG identifiers for published LRG records <string> Authentication key <array>  Here

getPending

Returns the LRG identifiers for pending LRG records <string> Authentication key <array>  Here

getStatus 

Returns the status of a specified LRG id, e.g. public, pending <string> Authentication key
<string> LRG id
<string>  Here

getLRGId

Returns LRG identifier(s) (if available) for an array of supplied HGNC symbols

<string> Authentication key
<array> HGNC symbols

<struct>  Here

getLRGIdFromXref

Returns LRG identifier(s) (if available) for an array of supplied synonym symbols and/or external reference identifiers.

<string> Authentication key
<array> symbols

<struct>  Here

getSymbol

Returns HGNC symbols (if available) for an array of supplied LRG identifiers

<string> Authentication key
<array> LRG ids

<struct>  Here
getReferenceTranscriptSource Returns the LRG transcript(s) of the specified LRG id and the accession of the source transcript that it was based on when created, typically a RefSeq identifier

<string> Authentication key
<string> LRG id

<struct>  Here

getMapping

Returns the mapping of the supplied LRG id to the specified genome assembly

<string> Authentication key
<string> LRG id
<string> Assembly

<struct>  Here
getReferenceSequence Returns the genomic LRG sequence for a specified LRG id

<string> Authentication key
<string> LRG id

<string>  Here
getReferenceAllele Returns the LRG reference allele for the supplied LRG identifier and (1-based) start and end coordinates

<string> Authentication key
<string> LRG id
<int> start
<int> end

<string>  Here
getcDNA Returns the cDNA sequence for a specified LRG id and transcript

<string> Authentication key
<string> LRG id
<string> LRG transcript name

<string>  Here
getCDS Returns the CDS for a specified LRG id and transcript

<string> Authentication key
<string> LRG id
<string> LRG transcript name

<string>  Here
getTranslation Returns the translated peptide sequence for a specified LRG id and transcript

<string> Authentication key
<string> LRG id
<string> LRG transcript name

<string>  Here

 

Examples in PHP:

 

getCoordinates

<?php
// Initialize the client
require_once 'XML/RPC2/Client.php';
$uri = 'http://www.lrg-sequence.org/xmlrpc.php';   
$options = array('prefix' => 'lrg_service.');
$client = XML_RPC2_Client::create($uri,$options);

// Input
$key = <put_your_authentication_key>;
$id = "LRG_1";
$format = 'json';

// Web service
try {
  $res = $client->getCoordinates($key,$id,$format);
  echo $res;
}  catch (Exception $e) {  
  // Other errors (HTTP or networking problems...)
  die('Exception : ' . $e->getMessage());
}
</php>

 And the result is:

{ "start":48259457, "end":48259457, "strand":-1, "region":"17", "assembly":"GRCh37.p10" }

 

 

getPublic

<?php
// Initialize the client
require_once 'XML/RPC2/Client.php';
$uri = 'http://www.lrg-sequence.org/xmlrpc.php';   
$options = array('prefix' => 'lrg_service.');
$client = XML_RPC2_Client::create($uri,$options);

// Input
$key = <put_your_authentication_key>;

// Web service
try {
  $res = $client->getPublic($key);
  echo "Count: ".count($res)."<br />";
  foreach ($res as $lrgid) {
    echo "$lrgid<br />";
  }
}  catch (Exception $e) {  
  // Other errors (HTTP or networking problems...)
  die('Exception : ' . $e->getMessage());
}
?>

 And the result is:

Count: 393
LRG_219
LRG_392
LRG_248
...

 

 

getPending

<?php
// Initialize the client
require_once 'XML/RPC2/Client.php';
$uri = 'http://www.lrg-sequence.org/xmlrpc.php';   
$options = array('prefix' => 'lrg_service.');
$client = XML_RPC2_Client::create($uri,$options);

// Input
$key = <put_your_authentication_key>;

// Web service
try {
  $res = $client->getPending($key);
  echo "Count: ".count($res)."<br />";
  foreach ($res as $lrgid) {
    echo "$lrgid<br />";
  }
}  catch (Exception $e) {  
  // Other errors (HTTP or networking problems...)
  die('Exception : ' . $e->getMessage());
}
?>

 And the result is:

Count:264
LRG_728
LRG_305
LRG_479
...

 

 

getStatus

<?php
// Initialize the client
require_once 'XML/RPC2/Client.php';
$uri = 'http://www.lrg-sequence.org/xmlrpc.php';   
$options = array('prefix' => 'lrg_service.');
$client = XML_RPC2_Client::create($uri,$options);

// Input
$key = <put_your_authentication_key>;
$id = 'LRG_1';

// Web service
try {
  $res = $client->getStatus($key,$id);
  echo "Status of $id: $res";
  }
}  catch (Exception $e) {  
  // Other errors (HTTP or networking problems...)
  die('Exception : ' . $e->getMessage());
}
?>

 And the result is:

Status of LRG_1: public

 

 

getLRGId

<?php
// Initialize the client
require_once 'XML/RPC2/Client.php';
$uri = 'http://www.lrg-sequence.org/xmlrpc.php';   
$options = array('prefix' => 'lrg_service.');
$client = XML_RPC2_Client::create($uri,$options);

// Input
$key = <put_your_authentication_key>;
$hgnc_symbol = array('LEPRE1','COL1A1');

// Web service
try {
  $res = $client->getLRGId($key,$hgnc_symbol);
  foreach ($res as $lrgids) {
    foreach ($lrgids as $lrgid) {
      echo "$lrgid<br />";
    }
  }
}  catch (Exception $e) {  
   // Other errors (HTTP or networking problems...)
   die('Exception : ' . $e->getMessage());
}
</php>

 And the result is:

LRG_1
LRG_5

 

 

getLRGIdFromXref

<?php
// Initialize the client
require_once 'XML/RPC2/Client.php';
$uri = 'http://www.lrg-sequence.org/xmlrpc.php';   
$options = array('prefix' => 'lrg_service.');
$client = XML_RPC2_Client::create($uri,$options);

// Input
$key = <put_your_authentication_key>;
$xref =  array('LEPRE1');

// Web service
try {
  $res = $client->getLRGIdFromXref($key,$xref);
  foreach ($res as $lrgids) {
   echo "Count: ".count($lrgids)."<br />";
    foreach ($lrgids as $lrgid) {
      echo "$lrgid<br />";
    }
  }
}  catch (Exception $e) {  
  // Other errors (HTTP or networking problems...)
  die('Exception : ' . $e->getMessage());
}
?>

 And the result is:

Count: 1
LRG_5

 

 

getSymbol

<?php
// Initialize the client
require_once 'XML/RPC2/Client.php';
$uri = 'http://www.lrg-sequence.org/xmlrpc.php';   
$options = array('prefix' => 'lrg_service.');
$client = XML_RPC2_Client::create($uri,$options);

// Input
$key = <put_your_authentication_key>;
$ids = array('LRG_1', 'LRG_5');

// Web service
try {
  $res = $client->getSymbol($key,$ids);
  foreach ($res as $lrgid => $symbols) {
    echo "# $lrgid:<br />";
    foreach ($symbols as $symbol) {
      echo "$symbol<br />";
    }
  }
}  catch (Exception $e) {  
  // Other errors (HTTP or networking problems...)
  die('Exception : ' . $e->getMessage());
}
?>

 And the result is:

# LRG_5:
LEPRE1
# LRG_1:
COL1A1

 

 

getReferenceTranscriptSource

<?php
// Initialize the client
require_once 'XML/RPC2/Client.php';
$uri = 'http://www.lrg-sequence.org/xmlrpc.php';   
$options = array('prefix' => 'lrg_service.');
$client = XML_RPC2_Client::create($uri,$options);

// Input
$key = <put_your_authentication_key>;
$id = "LRG_5";

// Web service
try {
  $res = $client->getReferenceTranscriptSource($key,$id);
  echo "Count: ".count($res)."<br />";
  foreach ($res as $tr => $refseq) {
    echo "Transcript $tr: $refseq<br />";
  }
}  catch (Exception $e) {  
  // Other errors (HTTP or networking problems...)
  die('Exception : ' . $e->getMessage());
}
</php>

 And the result is:

Count: 2
LRG transcript t1: NM_022356.3
LRG transcript t2: NM_001146289.1

 

 

getMapping

<?php
// Initialize the client
require_once 'XML/RPC2/Client.php';
$uri = 'http://www.lrg-sequence.org/xmlrpc.php';   
$options = array('prefix' => 'lrg_service.');
$client = XML_RPC2_Client::create($uri,$options);

// Input
$key = <put_your_authentication_key>;
$id = "LRG_1";
$assembly = "GRCh37.p10";

// Web service
try {
  $res = $client->getMapping($key,$id,$assembly);
  echo "# Genomic mapping information: <br />";
  foreach ($res as $key => $value) {
    if ($key != 'mapping_span') {
      echo "$key: $value<br />";
    }
    else {
      echo "<br /># LRG mapping information: <br />";
      foreach ($value as $lrg_mappings) {
        foreach ($lrg_mappings as $lrg_key => $lrg_value) {
          if ($lrg_key != 'diff') {
            echo "- $lrg_key: $lrg_value<br />";
          }
          else {
            echo "<br /># Mapping differences information: <br />";
            foreach ($lrg_value as $lrg_diff_mappings) {
              foreach ($lrg_diff_mappings as $diff_key => $diff_value) {
                echo "- $diff_key: $diff_value<br />";
              }
            }
          }
        }
      }
    }
  }
}  catch (Exception $e) {  
  // Other errors (HTTP or networking problems...)
  die('Exception : ' . $e->getMessage());
}
</php>

 And the result is:

# Genomic mapping information:
coord_system: GRCh37.p10
other_name: 17
other_id: NC_000017.10
other_start: 48259457
other_end: 48284000

# LRG mapping information:
- lrg_start: 1
- lrg_end: 24544
- other_start: 48259457
- other_end: 48284000
- strand: -1

# Mapping differences information:
- type: mismatch
- lrg_start: 18506
- lrg_end: 18506
- other_start: 48265495
- other_end: 48265495
- lrg_sequence: G
- other_sequence: A

 

 

getReferenceSequence

<?php
// Initialize the client
require_once 'XML/RPC2/Client.php';
$uri = 'http://www.lrg-sequence.org/xmlrpc.php';   
$options = array('prefix' => 'lrg_service.');
$client = XML_RPC2_Client::create($uri,$options);

// Input
$key = <put_your_authentication_key>;
$id = "LRG_1";

// Web service
try {
  $res = $client->getReferenceSequence($key,$id);
  echo "Sequence: ".$res."<br />";
}  catch (Exception $e) {  
  // Other errors (HTTP or networking problems...)
  die('Exception : ' . $e->getMessage());
}
</php>

 And the result is:

Sequence:
TTTGCCCAGGCTGGAGTGCAATGGTGTGATCTCGGTTCA...

 

 

getReferenceAllele

<?php
// Initialize the client
require_once 'XML/RPC2/Client.php';
$uri = 'http://www.lrg-sequence.org/xmlrpc.php';   
$options = array('prefix' => 'lrg_service.');
$client = XML_RPC2_Client::create($uri,$options);

// Input
$key = <put_your_authentication_key>;
$id = "LRG_1";
$start = 5128;
$end = 5130;

// Web service
try {
  $res = $client->getReferenceAllele($key,$id,$start,$end);
  echo "Allele: ".$res."<br />";
}  catch (Exception $e) {  
  // Other errors (HTTP or networking problems...)
  die('Exception : ' . $e->getMessage());
}
</php>

 And the result is:

Allele: TGT

 

 

getcDNA

<?php
// Initialize the client
require_once 'XML/RPC2/Client.php';
$uri = 'http://www.lrg-sequence.org/xmlrpc.php';   
$options = array('prefix' => 'lrg_service.');
$client = XML_RPC2_Client::create($uri,$options);

// Input
$key = <put_your_authentication_key>;
$id = "LRG_1";
$transcript = 't1';

// Web service
try {
  $res = $client->getcDNA($key,$id,$transcript);
  echo "cDNA: ".$res."<br />";
}  catch (Exception $e) {  
  // Other errors (HTTP or networking problems...)
  die('Exception : ' . $e->getMessage());
}
</php>

 And the result is:

cDNA: TCGTCGGAGCAGACGGGAGTTTCTCCTC...

 

 

getCDS

<?php
// Initialize the client
require_once 'XML/RPC2/Client.php';
$uri = 'http://www.lrg-sequence.org/xmlrpc.php';   
$options = array('prefix' => 'lrg_service.');
$client = XML_RPC2_Client::create($uri,$options);

// Input
$key = <put_your_authentication_key>;
$id = "LRG_1";
$transcript = 't1';

// Web service
try {
  $res = $client->getCDS($key,$id,$transcript);
  echo "CDS: ".$res."<br />";
}  catch (Exception $e) {  
  // Other errors (HTTP or networking problems...)
  die('Exception : ' . $e->getMessage());
}
</php>

 And the result is:

CDS: CATGTTCAGCTTTGTGGAC...

 

 

getTranslation

<?php
// Initialize the client
require_once 'XML/RPC2/Client.php';
$uri = 'http://www.lrg-sequence.org/xmlrpc.php';   
$options = array('prefix' => 'lrg_service.');
$client = XML_RPC2_Client::create($uri,$options);

// Input
$key = <put_your_authentication_key>;
$id = "LRG_1";
$transcript = 't1';

// Web service
try {
  $res = $client->getTranslation($key,$id,$transcript);
  echo "Translation: ".$res."<br />";
}  catch (Exception $e) {  
  // Other errors (HTTP or networking problems...)
  die('Exception : ' . $e->getMessage());
}
</php>

 And the result is:

Translation: MFSFVDLRLLLLLAATALLTHGQE...

 

 

Note:

You can use the option "debug" to display the structure of the request and server response, by using the following code

$options = array('debug' => true, 'prefix' => 'lrg_service.');

instead of

$options = array('prefix' => 'lrg_service.');

Example of XML request (using the debug option):

***** Request *****
<?xml version="1.0" encoding="utf-8"?>
<methodCall>
  <methodName>lrg_service.getLRGId</methodName>
  <params>
    <param>
      <value><string>***********************</string></value>
    </param>   
    <param>
      <value>
        <array>
          <data>
            <value><string>LEPRE1</string></value>
            <value><string>COL1A1</string></value>
          </data>
        </array>
      </value>
    </param>
  </params>
</methodCall>
***** End Of request *****
***** Server response *****
<?xml version="1.0"?>
<methodResponse>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>COL1A1</name>
            <value><array><data><value><string>LRG_1</string></value></data></array></value>
          </member>
          <member>
            <name>LEPRE1</name>
            <value><array><data><value><string>LRG_5</string></value></data></array></value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodResponse>
***** End of server response *****
***** Decoded result *****
Array
(
    [COL1A1] => Array
        (
            [0] => LRG_1
        )

    [LEPRE1] => Array
        (
            [0] => LRG_5
        )
)
***** End of decoded result *****

Client libraries for the XML-RPC protocol exist for a wide range of programming languages. A more extensive example of some calls using the web service functionality via the XML_RPC2 PHP client can be found here and the typical output from the example can be viewed here.

 


REST web services

The EMBL-EBI provides RESTful web services for LRG. It also provides client tools in several programming languages to query their RESTful web services and parse their outputs.

Web service root URL for LRG: http://www.ebi.ac.uk/ebisearch/ws/rest/lrg

The EMBL-EBI RESTful web services provide several output format such as: XML, JSON, CSV, TSV.

These web services don't need an authentication key.

Here are listed differents type of calls, which replace the deprecated LRG web services. They are classified in 2 main types of queries:

1. Search LRG(s)

Get list of public LRGs (equivalent of getPublic)

Query: ?query=status:public

Example: http://www.ebi.ac.uk/ebisearch/ws/rest/lrg?query=status:public&size=100

The particularity of the EMBL-EBI REST web service is it only returns a maximum of 100 results at a time.

To retrieve all the data, if the total of entries is greater than 100, you need to use the pagination, e.g.:

Looking at the tag "hitCount" you can see how many entries have been found, and then you can loop over this number to retrieve all the results. Let's say the total number of result is <hitCount>663</hitCount>, we have to loop like this:

http://www.ebi.ac.uk/ebisearch/ws/rest/lrg?query=status:public&size=100&start=0

http://www.ebi.ac.uk/ebisearch/ws/rest/lrg?query=status:public&size=100&start=100

http://www.ebi.ac.uk/ebisearch/ws/rest/lrg?query=status:public&size=100&start=200

...

http://www.ebi.ac.uk/ebisearch/ws/rest/lrg?query=status:public&size=100&start=600

Get list of pending LRGs (equivalent of getPending)

Query: ?query=status:pending

Example: http://www.ebi.ac.uk/ebisearch/ws/rest/lrg?query=status:pending&size=100

Same as the section above "Get list of public LRGs", replacing the status "public" by "pending".

Retrieve a LRG using a HGNC symbol (equivalent of getLRGId)

Query: ?query=name:<HGNC_symbol>

Example: http://www.ebi.ac.uk/ebisearch/ws/rest/lrg?query=name:COL1A1

Retrieve a LRG using external references (equivalent of getLRGIdFromXref)

 

2. Get data from one or several LRGs

Get the genomic coordinates of a list of LRGs (equivalent of getCoordinates and getMapping)
Get the status of a list of LRGs (equivalent of getStatus)

URL syntax: /entry/<lrg_ids_list>?fields=status

Example for one LRG: /entry/LRG_1?fields=status

Example for several LRGs: /entry/LRG_1,LRG_2?fields=status

Get the HGNC symbols of a list of LRGs (equivalent of getSymbol)

URL syntax: /entry/<lrg_ids_list>?fields=name

Example for one LRG: /entry/LRG_1?fields=name

Example for several LRGs: /entry/LRG_1,LRG_2?fields=name