METLIN WEB-API [SOAP] Documentation

WSDL (Web Services Description Language) : http://metlin.scripps.edu/soap/metlin-1.0.wsdl

Register here to receive valid token

Metabolite Search

- To obtain range of metabolites matching search parameters (mass, tolerance, adduct, etc.).

Parameter Type Description
Token String Register to receive a token.
Mass Array of float Specifies one or more masses to be searched. 500 mass limit.
Adduct Array of string Specifies one or more adducts to be selected.
Neutral : ('M')
Positive : ('M+H','M+NH4','M+Na','M+H-2H2O','M+H-H2O','M+K','M+ACN+H', 'M+ACN+Na','M+2Na-H',
                  'M+2H','M+3H','M+H+Na','M+2H+Na','M+2Na','M+2Na+H')
Negative : ('M-H','M-H2O-H','M+Na-2H','M+Cl','M+K-2H','M+FA-H','M-2H','M-3H')
Tolerance Float Specifies amount of tolerance (< 1 Da or < 1000 ppm).
Tolerance units String Specifies the units of tolerance (Da or ppm).


Below is a sample php-SOAP client [Please feel free to copy and use this as a template]:

<?php
ini_set('soap.wsdl_cache_enable', 0 );

// Batch search for multiple masses and adducts
$token = "myToken";
$mass = array(195.0877,181.0702);
$adduct = array('M+H','M+Na','M+K');
$tolunits = "ppm";
$tolerance = 30;

// Search parameters. Can also use a class instead of an array to map "mass", "adduct", ... to their corresponding value
// Can call the SoapClient functions _getTypes() and _getFunctions() to see the required types and structures for the WSDL
$parameters = array("token" => $token, "mass" => $mass, "adduct" => $adduct, "tolerance" => $tolerance, "tolunits" => $tolunits);

// Call the MeatboliteSearch function via the soap service
try{
    $client = new SoapClient("http://metlin.scripps.edu/soap/metlin-1.0.wsdl");
    $return = $client->MetaboliteSearch($parameters);

}catch (SoapFault $fault){
    echo $fault;
    trigger_error("SOAP Fault: (faultcode: {$fault->faultcode}, faultstring: {$fault->faultstring})", E_USER_ERROR);
}

/* The SOAP return variable for the MetaboliteSearch function is struct containing a 2-D array
* with the format: $return[all adduct/mass combos][metabolites returned from each combo]. Adduct/mass
* combinations are stored in the array as follows: for a seach of adducts (a1,a2,...,an) and masses (m1,m2,...,mn)
* the results are stored in the array as result (a1/m1,a1/m2,...,a2/m1,...,an/mn) with each adduct mass combo
* mapping to an array of metabolites that matches the particular adduct mass search.
*/

$count = 0;

for($i = 0; $i<count($adduct); $i++){
    echo("<br><b><u>Adduct: $adduct[$i] </u></b></br>");
    for($j=0; $j<count($mass); $j++){
        echo("<br><b>Mass: $mass[$j] </b>");

        $AMCombo = $return[$count];
        echo("&nbsp;&nbsp;<b>Results: ".count($AMCombo)."</b>");

        if(count($AMCombo) > 0){
            echo "<table border='1' width=90% style='table-layout:fixed'><tr><td width = '7%'>METLIN ID</td>
                 <td width = '7%'>MASS</td><td width='36%'>NAME</td><td width='10%'>FORMULA</td>
                 <td width = '10%'>ADDUCT</td></tr>";

             // Display each metabolite
            foreach($AMCombo as $singleSearchResults){
                echo "<tr>";
                echo "<td><a href=\"http://metlin.scripps.edu/metabo_info.php?molid=".$singleSearchResults->molid."\">".$singleSearchResults->molid."</a></td>";
                echo "<td>".number_format($singleSearchResults->mass,4)."</td>";
                echo "<td>".$singleSearchResults->name."</td>";
                echo "<td>".$singleSearchResults->formula."</td>";
                echo "<td> $adduct[$i] </td>";
                echo "</tr>";
            }
            echo "</table>";
        }else echo "<br>"; ;
        $count++;
    }
}
?>


Search Results -> Below is the response to the sample client above:


Adduct: M+H

Mass: 195.0877   Results: 15
METLIN ID MASSNAMEFORMULA ADDUCT
1455194.0804CaffeineC8H10N4O2 M+H
6958194.0790D-GlucosideC7H14O6 M+H
43514194.08449-AminoacridineC13H10N2 M+H
44659194.0790QUEBRACHITOLC7H14O6 M+H
63284194.07903-O-Methyl-myo-inositolC7H14O6 M+H
63285194.07901-O-Methyl-myo-inositolC7H14O6 M+H
85437194.0804EnprofyllineC8H10N4O2 M+H
86585194.0790D-4-O-Methyl-myo-inositolC7H14O6 M+H
86586194.07904-O-Methyl-myo-inositolC7H14O6 M+H
86622194.0790Methyl beta-D-glucopyranosideC7H14O6 M+H
87689194.0790SequoyitolC7H14O6 M+H
89550194.0790MytilitolC7H14O6 M+H
89783194.0790D-PinitolC7H14O6 M+H
89784194.0790L-PinitolC7H14O6 M+H
92244194.07993-[(2-Mercapto-1-methylpropyl)thio]-2-butanolC8H18OS2 M+H

Mass: 181.0702   Results: 29
METLIN ID MASSNAMEFORMULA ADDUCT
133180.0634α-D-GlucoseC6H12O6 M+H
134180.0634D-GalactoseC6H12O6 M+H
135180.0634FructoseC6H12O6 M+H
136180.0634D-(+)-MannoseC6H12O6 M+H
144180.0634myo-InositolC6H12O6 M+H
348180.0634AlloseC6H12O6 M+H
1456180.0647TheobromineC7H8N4O2 M+H
1457180.0647ParaxanthineC7H8N4O2 M+H
1458180.0647TheophyllineC7H8N4O2 M+H
3317180.0634L-(-)SorboseC6H12O6 M+H
3754180.0634b-D-GalactopyranoseC6H12O6 M+H
3755180.0634b-GlucoseC6H12O6 M+H
4131180.06341,3-DihydroxyacetoneC6H12O6 M+H
4184180.0634L-GalactoseC6H12O6 M+H
5335180.06343-Deoxyarabinohexonic acidC6H12O6 M+H
44877180.0634allo-InositolC6H12O6 M+H
58151180.0634D-TagatoseC6H12O6 M+H
63118180.0634α-D-GlucoseC6H12O6 M+H
63163180.0634L-RhamnonateC6H12O6 M+H
63168180.0634D-FuconateC6H12O6 M+H
63197180.0634β-D-FructoseC6H12O6 M+H
64618180.0634L-(+)-GuloseC6H12O6 M+H
65598180.0634SorboseC6H12O6 M+H
65675180.0634D-HamameloseC6H12O6 M+H
65829180.06342-Deoxy-D-gluconateC6H12O6 M+H
66498180.0575Fluoren-9-oneC13H8O M+H
66926180.0634beta-D-HamamelopyranoseC6H12O6 M+H
68675180.0634D-FructoseC6H12O6 M+H
93528180.057512-Tridecene-4,6,8,10-tetraynalC13H8O M+H

Adduct: M+Na

Mass: 195.0877   Results: 3
METLIN ID MASSNAMEFORMULA ADDUCT
44284172.1000NORELEAGNINEC11H12N2 M+Na
44431172.1000DESOXYPEGANINEC11H12N2 M+Na
72278172.0960L-CapreomycidineC6H12N4O2 M+Na

Mass: 181.0702   Results: 4
METLIN ID MASSNAMEFORMULA ADDUCT
63058158.08441-BenzylimidazoleC10H10N2 M+Na
68165158.0844NicotyrineC10H10N2 M+Na
73157158.08441,5-NaphthalenediamineC10H10N2 M+Na
88389158.0765S-Isopropyl 3-methylbut-2-enethioateC8H14OS M+Na

Adduct: M+K

Mass: 195.0877   Results: 1
METLIN ID MASSNAMEFORMULA ADDUCT

Mass: 181.0702   Results: 1
METLIN ID MASSNAMEFORMULA ADDUCT


Using Java:

Here is a sample Metabolite Search Java Client :


import java.io.IOException;
import java.net.URL;
import java.lang.String;
import java.util.Arrays;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import javax.activation.*;
import javax.mail.internet.*;
import metlin.*;

public class MetlinTest {
    private static final String adduct[] = { "M+H","M+Na","M+K" };
    public static void main(String args[]) {
        try {
            MetlinServiceLocator locator = new MetlinServiceLocator();
            MetlinPortType serv = locator.getMetlinPort();
            String token = "myToken";
            float searchMass[] = new float[] { 195.0877f,181.0702f };
            float searchTolerance = 30;
            String toleranceUnits = "ppm";
            MetaboliteSearchRequest parameters = new MetaboliteSearchRequest(token,searchMass,adduct, searchTolerance, toleranceUnits);
            LineInfo resultsData[][] = serv.metaboliteSearch(parameters);
            for(int i = 0; i < adduct.length*searchMass.length; i++){
                for(LineInfo line : resultsData[i]){
                    System.out.println(line.getMolid());
                    System.out.println(line.getMass());
                    System.out.println(line.getName());
                    System.out.println(line.getFormula());
                    System.out.println();
                }
            }
        } catch (Exception e) {
             e.printStackTrace();
        }
    }
}

You will need to do the following in order to compile and run this example:
1. Download and install Apache Axis2.
2. Download and extract MZmine2 onto your harddrive. Move the "metlin-api-1.0" Jar file into your Axis/lib directory.
3. You may need to download the DataHandler and Activation Jar files into your directory, look for them on Google.
4. After you have created MetlinTest.java, in the Axis/lib directory; execute the following commands:

(Note that the WSDL file in the java is different from the link above.)

% java -cp .;* org.apache.axis.wsdl.WSDL2Java http://metlin.scripps.edu/soap/metlin-1.1.wsdl
% javac -classpath .;* MetlinTest.java
% java -cp .;* MetlinTest


Spectrum Match

- Spectrum Match facilitates identification of both known and unknown metabolites against METLIN MS/MS database using the modified X-Rank algorithm with your spectrum(m/z, intensity) and few parameters.

Parameter Type Description
Token String Register to receive a token. The same token can be used for both Metabolite Search and Spectrum Match.
Mass Array of float Specifies one or more masses to be searched. 30 mass limit.
Intensity Array of int Specifies one or more intensities. Each intensity corresponds with a mass (mass[0] will be paired with intensity[0]...). Number of intensities must equal the number of masses.
Mode String Specifies the mode. Must be either 'pos' or 'neg' exactly.
Collision Energy int Specifies the collision energy. Must be either 10, 20, or 40. Units are eV.
Tolerance MSMS float Specifies the tolerance of the MSMS data. Must be between 0.001 and 0.5. Units are Da.
Tolerance Precursor int Specifies the tolerance of the precursor. Must be between 1 and 100. Units are ppm.
Precursor Mass float Specifies the mass of the precursor.


Below is a sample php-SOAP client [Please feel free to copy and use this as a template]:

<?php
ini_set('soap.wsdl_cache_enable', 0 );

// Spectrum Match Parameters
$token = "myToken";
$specMasses = array(138.066,110.071,42.034,69.045,123.043,83.060,109.036);
$intensity = array(10877,2221,644,351,350,318,234);
$mode = "pos";
$ce = 20;
$tolMS = 0.01;
$tolPrec = 20;
$prec = 195.0877;

// Search parameters. Can also use a class instead of an array to map "token", "mass", ... to their corresponding value
// Can call the SoapClient functions _getTypes() and _getFunctions() to see the required types and structures for the WSDL
$specparam = array("token"=>$token, "mass" => $specMasses, "intensity" => $intensity, "mode" => $mode, "collisionEnergy" => $ce, "toleranceMSMS" => $tolMS, "tolerancePrecursor" => $tolPrec, "precursorMass" => $prec);

// Call the SpectrumMatch function via the soap service
try{
    $client = new SoapClient("http://metlin.scripps.edu/soap/metlin-1.0.wsdl");
    $return = $client->SpectrumMatch($specparam);

}catch (SoapFault $fault){
    echo $fault;
    trigger_error("SOAP Fault: faultcode:". ($fault->faultcode), $fault->faultstring);
}

/* The SOAP return variable for the SpectrumMatch function is a struct containing a 2-D array
* with the format: $return->SpectrumMatchResult[# of results][line info on each result].
*/

$count = count($return);

if($count < 1){
    echo "No result is returned, please try again with different parameters!!";
} else{
    echo "<table align =\"center\" border=\"1\" cellpadding = \"3\" bordercolor = \"#747170\"><tr>";
    echo "<th align = \"center\" valign=\"top\">METLIN ID</th>";
    echo "<th align = \"center\" valign=\"top\">Name</th>";
    echo "<th align = \"center\" valign=\"top\">METLIN Score<br/>(0-100)</th>";
    echo "<th align = \"center\" valign=\"top\">precursor</th>";
    echo "<th align = \"center\" valign=\"top\">precursor<br/>ΔPPM</th>";
    echo "<th align = \"center\" valign=\"top\">Spectrum Matching</th></tr>";

    for($i=0 ; $i < $count ; $i++){
        $metlinID = $return[$i][0]->value;
        $name = $return[$i][1]->value;
        $metlinScore = $return[$i][2]->value;
        $precursor = $return[$i][3]->value;
        $precursorPPM = $return[$i][4]->value;
        $spectrumMatching = $return[$i][5]->value;
        echo '<tr><td align = "center" width="80"><a href="http://metlin.scripps.edu/metabo_info.php?molid='.$metlinID.'">'.$metlinID."</a></td>";
        echo '<td width="200">'.$name.'</td>';
        echo "<td align='center'>".$metlinScore."</td>";
        echo "<td align='center'>".$precursor."</td>";
        echo "<td align='center'>".$precursorPPM."</td>";
        echo '<td width="240"> <a href="'.$spectrumMatching.'" class="highslide" onclick="return hs.expand(this)"> <img src= "'.$spectrumMatching.'" alt ='.$metlinID.' title= "Click to enlarge" width = "240" height = "150"></a></td></tr>';
    }
     echo "</table>";
}
?>


Search Results -> Below is a screen shot of the response to the sample client above:



Using Java:

Here is a sample Spectrum Match Java Client :

Note: Due to versioning issues, this client seems to have compliance issues. A new version of the WSDL and Client code will be released soon, which will implement the newer standards.


import java.io.IOException;
import java.net.URL;
import java.lang.String;
import java.util.Arrays;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import metlin.*;

public class SpectrumTest{
    public static void main(String args[]) {
        try {
            MetlinServiceLocator locator = new MetlinServiceLocator();
            MetlinPortType serv = locator.getMetlinPort();
            String token = "myToken";
            float specMass[] = new float[] { 138.066f,110.071f,42.034f,69.045f,123.043f,83.060f,109.036f };
            int intensity[] = new int[] { 10877,2221,644,351,350,318,234 };
            String mode = "pos";
            int ce = 20;
            float tolMS = 0.01f;
            int tolPrec = 20;
            float prec = 195.0877f;
            SpectrumMatchRequest parameters = new SpectrumMatchRequest(token, specMass, intensity, mode, ce, tolMS, tolPrec, prec);
            SpectrumLineInfo resultsData[]= serv.spectrumMatch(parameters);
            for(int i = 0; i < resultsData.length; i++){
                System.out.println(resultsData[i].getMetlinID());
                System.out.println(resultsData[i].getName());
                System.out.println(resultsData[i].getMetlinScore());
                System.out.println(resultsData[i].getPrecursor());
                System.out.println(resultsData[i].getPrecursorPPM());
                System.out.println(resultsData[i].getSpectrumMatching());
            }
        } catch (Exception e) {
             e.printStackTrace();
        }
    }
}

You will need to do the following in order to compile and run this example:
1. Download and install Apache Axis2.
2. Download and extract MZmine2 onto your harddrive. Move the "metlin-api-1.0" Jar file into your Axis/lib directory.
3. You may need to download the DataHandler and Activation Jar files into your directory, look for them on Google.
4. After you have created SpectrumMatch.java, in the Axis/lib directory; execute the following commands:

% java -cp .;* org.apache.axis.wsdl.WSDL2Java http://metlin.scripps.edu/soap/metlin-1.1.wsdl
% javac -classpath .;* MetlinTest.java
% java -cp .;* MetlinTest