Help - APIs

Advanced use via APIs

This Metabolome Repository system provides a set of APIs (Application Programming Interfaces) by which other programs can use the repository data directly. By accessing the URLs written in specified formats, users can see the results on a browser, can get the results in JSON format (text), and can download data files. Especially, the APIs that returns JSON format are useful to integrate the search functions in other programs and to perform a large amount of searches.

This document show the use of the APIs in detail. The system is now used in several repository for metabolome data obtained form non-food samples. For the convenience of the maintenance of this document, the examples are represented using Food Metabolome Repository.

Sample programs

Program codes written in Python are available as examples of the use of APIs.

Searching candidates of novel flavonoids
Searching sample(s) specific peaks.


Displaying the results on a browser

Displaying peaks searched by a mass value and a retention time

Format /search/precursor /TARGET /MASS /MASS_TOLERANCE /MASS_TOLERANCE_UNIT /TYPE
/search/precursor /TARGET /MASS /MASS_TOLERANCE /MASS_TOLERANCE_UNIT /TYPE /RT /RT_TOLERANCE
Variable TARGET: mz, detected m/z value or mzdi, molecular mass after removal of adduct
MASS: a mass value
MASS_TOLERANCE: a tolerance of the mass value. At a maximum of 10 Da is allowed
MASS_TOLERANCE_UNIT: unit of the mass tolerance. ppm or da
TYPE: detection mode. pos, neg, or both
Retention time limitation is not applied when omitting parameters below.
RT: a retention time
RT_TOLERANCE: a tolerance of the retention time (min)
Example /search/precursor /mz /611.1611 /5 /ppm /pos
/search/precursor /mzdi /307 /0.5 /da /both /13 /1
Status Since version 1.3.0
Description A list of peaks matched the condition and a summary is displayed on a browser. The peak icons are roughly aligned by their retention time.

Displaying peaks searched by a mass value and a retention time (Older version)

Format /search /TARGET /MASS /MASS_TOLERANCE /MASS_TOLERANCE_UNIT /TYPE
/search/TARGET /MASS /MASS_TOLERANCE /MASS_TOLERANCE_UNIT /TYPE /RT /RT_TOLERANCE
Variable TARGET: mz, detected m/z value or mzdi, molecular mass after removal of adduct
MASS: a mass value
MASS_TOLERANCE: a tolerance of the mass value. At a maximum of 10 Da is allowed
MASS_TOLERANCE_UNIT: unit of the mass tolerance. ppm or da
TYPE: detection mode. pos, neg, or both
Retention time limitation is not applied when omitting parameters below.
RT: a retention time
RT_TOLERANCE: a tolerance of the retention time (min)
Example /search /mz /611.1611 /5 /ppm /pos
/search /mzdi /307 /0.5 /da /both /13 /1
Description A list of peaks matched the condition and a summary is displayed on a browser. The peaks matched are displayed in a single cell.

Displaying peaks with MS2 or MS3 spectra searched by a query spectrum

Format /search/spectrum /SPECTRUM_STRING
/search/spectru m/SPECTRUM_STRING /MIN_SCORE /MAX_RESULT_NUM
Variable SPECTRUM_STRING: A string of query spectrum. Concatenate m/z value and intensity with a comma ',' to make an ion, and concatenate ions with colons ":". The m/z values are rounded during the search.

The default values are applied when the following parameters are omitted.
MIN_SCORE: The minimum value of the similarity score (dot product) to show. It must be more than 0.5. The default value is 0.9.
MAX_RESULT_NUM: The maximum number of the results. It must be less than 100. The default value is 10.
Example /search/spectrum /271.13,19406:229.05,12631:152.9,9846:225.12,6110:162.78,3851
/search/spectrum /271.13,19406:229.05,12631:152.9,9846:225.12,6110:162.78,3851 /0.8 /50
/search/spectrum /311.21,534873:357.23,450391:339.2,97498
/search/spectrum /311.21,534873:357.23,450391:339.2,97498 /0.8 /5
Description The peaks with MS2 or MS3 spectra are searched by the query spectra, and the results are displayed on the browser.

Displaying peak information

Format /peak /SAMPLE_NO /TYPE /PEAK_NO
Variable SAMPLE_NO: a sample id
TYPE: detection mode pos or neg
PEAK_NO: peak number
Example /peak /01026 /pos /8603
Description A detailed information of a peak specified by a sample id, detection mode and a peak number is displayed on a browser.

Getting the results in JSON format

A full description about key names and the structure of each JSON object was omitted here. Please check them in the results obtained by the examples

Getting statistics

Format /api/stat
Example /api/stat
Description Statistical information such as number of sample items and peaks. The prefix 'num' represents number in 'int' value, and the prefix 'ratio' represents ratio in 'float' value.

Getting a sample list

Format /api/samples
Example /api/samples
Status Since version 1.3.0
Description A full sample list is obtained in JSON format.

Getting a sample list (Deprecated)

Format /api/foods
Example /api/foods
Status Deprecated (version 1.3.0 or later)
Description A full sample list is obtained in JSON format. The path name was changed to a general one for use of this system to the metabolome data obtained from various samples. Please use a newer one that returns the same results.

Getting a sample list (for published items)

Format /api/samples/published
Example /api/samples/published
Status Since version 1.3.0
Description A list of sample with published data is obtained in JSON format.

Getting a sample list (for published items) (Deprecated)

Format /api/foods/published
Example /api/foods/published
Status Deprecated (version 1.3.0 or later)
Description A list of sample with published data is obtained in JSON format. The path name was changed to a general one for use of this system to the metabolome data obtained from various samples. Please use a newer one that returns the same results.

Getting a peak list detected in a sample

Format /api/peaklist /SAMPLE_NO /TYPE
Variable SAMPLE_NO: a sample id
TYPE: detection mode. pos or neg
Example /api/peaklist /01026 /pos
Description A list of detected peaks in a specified sample and detection mode is obtained in JSON format.

Getting peak information

Format /api/peak /SAMPLE_NO /TYPE /PEAK_NO
Variable SAMPLE_NO: a sample id
TYPE: detection mode. pos or neg
PEAK_NO: a peak id
Example /api/peak /04032 /pos /6461
Description A detailed informatio of a peak in a specified sample, detection mode, and a peak id is obtained in JSON format.

Getting MS spectra for a peak

Format /api/msn /SAMPLE_NO /TYPE /PEAK_NO
Variable SAMPLE_NO: a sample id
TYPE: detection mode. pos or neg
PEAK_NO: a peak id
Example /api/msn /04032 /pos /6461
Description A MSn spectra information of a peak in a specified sample, detection mode and a peak id is obtaine in JSON format.

Getting peaks searched by a mass value and a retention time

Format /api/search/peaks /TARGET /MASS /MASS_TOLERANCE /MASS_TOLERANCE_UNIT /TYPE
/api/search/peaks /TARGET /MASS /MASS_TOLERANCE /MASS_TOLERANCE_UNIT /TYPE /RT /RT_TOLERANCE
Variable TARGET: mz, detected m/z value; or mzdi, molecular mass value after removal of adduct
MASS: a mass value
MASS_TOLERANCE: a tolerance of the mass value. At a maximum of 10 Da is allowed.
MASS_TOLERANCE_UNIT: unit of the mass tolerance. ppm or da
TYPE: detection mode. pos, neg, or both
Retention time limitation is not applied when omitting parameters below.
RT: a retention time
RT_TOLERANCE: a tolerance of the retention time (min)
Example /api/search/peaks /mz /611.1611 /5 /ppm /pos
/api/search/peaks /mzdi /307 /0.5 /da /both /13 /1
Description A list of peaks matched the conditions is obtained in JSON format.

Getting summary of peaks searched by a mass value and a retention time

Format /api/search/summary /TARGET /MASS /MASS_TOLERANCE /MASS_TOLERANCE_UNIT /TYPE
/api/search/summary /TARGET /MASS /MASS_TOLERANCE /MASS_TOLERANCE_UNIT /TYPE /RT /RT_TOLERANCE
Variable TARGET: mz, detected m/z value; or mzdi, molecular mass value after removal of adduct
MASS: a mass value
MASS_TOLERANCE: a tolerance of the mass value. At the maximum of 10 Da is allowed.
MASS_TOLERANCE_UNIT: unit of the mass tolerance. ppm or da
TYPE: detection mode. pos, neg, or both
Retention time limitation is not applied when omitting parameters below.
RT: a retention time
RT_TOLERANCE: a tolerance of the retention time (min)
Example /api/search/summary /mz /611.1611 /5 /ppm /pos
/api/search/summary /mzdi /307 /0.5 /da /both /13 /1
Description A summary of the sample that the peaks were found by the search condition in the sample groups is obtained in JSON format.

Getting peaks with MS2 or MS3 spectra searched by a query spectrum

Format /api/search/spectrum /SPECTRUM_STRING
/api/search/spectrum /SPECTRUM_STRING /MIN_SCORE
Variable SPECTRUM_STRING: A string of query spectrum. Concatenate m/z value and intensity with a comma ',' to make an ion, and concatenate ions with colons ":". The m/z values are rounded during the search.

The default values are applied when the following parameters are omitted.
MIN_SCORE: The minimum value of the similarity score (dot product) to show. It must be more than 0.5. The default value is 0.9.
Example /api/search/spectrum /271.13,19406:229.05,12631:152.9,9846:225.12,6110:162.78,3851
/api/search/spectrum /271.13,19406:229.05,12631:152.9,9846:225.12,6110:162.78,3851 /0.8
/api/search/spectrum /311.21,534873:357.23,450391:339.2,97498
/api/search/spectrum /311.21,534873:357.23,450391:339.2,97498 /0.8
Description The peaks with MS2 or MS3 spectra are searched by the query spectra, and the results are obtained in JSON format.

Getting the number of spectra with a specified neutral loss mass

Format /api/search/nl/count /NL_MASS /MASS_TOLERANCE /NUM_TOP_IONS /MIN_INT_RATIO /TYPE /MS_LEVEL
Variable NL_MASS: a neutral loss mass
MASS_TOLERANCE: tolerance of the neutral loss mass (Da)
NUM_TOP_IONS: Number of ions for search. Ions with higher intensity in the spectra are used.
MIN_INT_RATIO: The ratio to the base peak ion which is used for calculation of intensity threshold for the target ions. The threshold is used to filter the ions with 2nd highest intensity and lower.
TYPE: detection mode: pos, neg, or both
MS_LEVEL: mass level. 2 for MS2, 3 for MS3, or all
Example /api/search/nl /132 /0.5 /1 /0.5 /pos /all
Status Since version 1.3.0
Description The number of spectra that has specified neutral loss mass, and the results are obtained in JSON format. The mas tolerance should be set with consideration of the mass acuracy of the spectrometer. The number of spectra might be very large depending on the search conditions. Therefore, this API can be used prior to acquisision of spectral data using this API.

Getting the spectra with a specified neutral loss mass

Format /api/search/nl/spectra /NL_MASS /MASS_TOLERANCE /NUM_TOP_IONS /MIN_INT_RATIO /TYPE /MS_LEVEL /SAMPLE_NO
Variable NL_MASS: a neutral loss mas value
MASS_TOLERANCE: tolerance of the neutral loss mass (Da)
NUM_TOP_IONS: Number of ions for search. Ions with higher intensity in the spectra are used.
MIN_INT_RATIO: The ratio to the base peak ion which is used for calculation of intensity threshold for the target ions. The threshold is used to filter the ions with 2nd highest intensity and lower.
TYPE: detection mode: pos, neg, or both
MS_LEVEL: mass level. 2 for MS2, 3 for MS3, or all
SAMPLE_NO: a sample id for search
Example /api/search/nl/spectra /132 /0.5 /1 /0.5 /pos /all /01026
Status Since version 1.3.0
Description The spectral data with a specified neutral loss in a specified sample are searched and the results are obtained in a JSON format. The number of spectra might be very large depending on the search condition. Be careful when using this API for large-scale automatic searching.

Getting a list of mass chromatogram data (ZIP files) for download

Format /api/dl-info-chrom /SAMPLE_NO
Variable SAMPLE_NO: a sample id
Example /api/dl-info-chrom /01026
Status Since version 1.4.0
Description Information of the ZIP files for the downloadable mass chromatogram data is available as a list. The list contains the Metabolonote ID which is unique in the sample set and used for specifying the data file, the file size (MB), the file name, and so on.

Getting information of peak data (ZIP file) for download

Format /api/dl-info-peaks /SAMPLE_NO
Variable SAMPLE_NO: a sample id
Example /api/dl-info-peaks /01026
Status Since version 1.4.0
Description The file name and the file size (MB) of the ZIP file which contains peak list, MSn data, and assigned used in the peak list is available.

Getting file size of a ZIP file (Deprecated)

Format /api/dlsize /FILE_TYPE /SAMPLE_NO /MODE
Variable FILE_TYPE: raw, mzXML, or peak
SAMPLE_NO: a sample id
MODE: detection mode. pos, or neg
Example /api/dlsize /peak /01026 /pos
Status Deprecated (version 1.4.0 or later)
Description Information of file name and file size (MB) of the zip compressed data is obtained in JSON format. Downloading is not performed by this API. Binary raw data (raw), mass chromatogram data converted into mzXML format (mzXML), and a set of peak list and MS spectra data (peak) are available for each sample analyzed by positive and negative modes.

Getting the images

Getting a image of 2D chromatogram

Format /api/img/chrm /SAMPLE_NO /MODE
Variable SAMPLE_NO: a sample id
MODE: detection mode. pos, or neg
Example /api/img /chrm /01026 /pos
Description A 2-dimensional (2D) chromatogram of sample analysis using LC-MS (x-axis: retention time, y-axis: m/z value) is obtained.

Getting a image of a sample

Format /api/img/sample /SAMPLE_NO
変数 SAMPLE_NO: sample id
Example /api/img/sample /01026
Status Since version 1.3.0
Description A image of analyzed sample is obtained. The sample image is for illustration purposes, and may differ from the sample which was actually analyzed here.

Getting a image of a sample (Deprecated)

Format /api/img/food /SAMPLE_NO
Variable SAMPLE_NO: a sample id
Example /api/img/food /01026
Status Deprecated (version 1.3.0 or later)
Description A image of analyzed sample is obtained. The sample image is for illustration purposes, and may differ from the sample which was actually analyzed here. The path name was changed to a general one for use of this system to the metabolome data obtained from various samples. Please use a newer one that returns the same results.

Getting a image of 2D chromatogram with a sample image

Format /api/img/chrm-sample /SAMPLE_NO /MODE
変数 SAMPLE_NO: a sample id
MODE: pos or neg
Example /api/img/chrm-sample /01026 /pos
Status Since version 1.3.0
Description A 2-dimensional (2D) chromatogram of the sample analysed using LC-MS (x-axis: retention time, y-axis: m/z value) with an insertion of a sample image at the top-right is obtained. The sample image is for illustration purposes, and may differ from the sample which was actually analyzed here.

Getting a image of 2D chromatogram with a sample image (Deprecated)

Format /api/img/chrmfood /SAMPLE_NO /MODE
Variable SAMPLE_NO: a sample id
MODE: detection mode. pos, or neg
Example /api/img/chrmfood /01026 /pos
Status Deprecated (version 1.3.0 or later)
Description A 2-dimensional (2D) chromatogram of the sample analyzed using LC-MS (x-axis: retention time, y-axis: m/z value) with an insertion of a sample image at the top-right is obtained. The sample image is for illustration purposes, and may differ from the sample which was actually analyzed here. The path name was changed to a general one for use of this system to the metabolome data obtained from various samples. Please use a newer one that returns the same results.

Downloading

Download a ZIP file of chromatogram data (raw)

Format /api/dl-raw /SAMPLE_NO /MN-ID
Variable SAMPLE_NO: a sample id
MN-ID: a Metabolonote ID
Example /api/dl-raw /01026 /SE112_S010261_M01
Status Since version 1.4.0
Description The ZIP file for mass chromatogram data (raw) is available. The unique Metabolonote ID which specifies the data in the sample set, and its file size (MB) are available via another API

Download a ZIP file of chromatogram data (mzXML)

Format /api/dl-mzxml /SAMPLE_NO /MN-ID
Variable SAMPLE_NO: a sample id
MN-ID: a Metabolonote ID
Example /api/dl-mzxml /01026 /SE112_S010261_M01
Status Since version 1.4.0
Description The ZIP file for mass chromatogram data (mzXML) is available. The unique Metabolonote ID which specifies the data in the sample set, and its file size (MB) are available via another API

Download a ZIP file of peak data

Format /api/dl-peaks /SAMPLE_NO
Variable SAMPLE_NO: a sample id
Example /api/dl-peaks /01026
Status Since version 1.4.0
Description The ZIP file for peak data is available.

Download a ZIP file (Deprecated)

Format /api/dl /FILE_TYPE /SAMPLE_NO /MODE
Variables FILE_TYPE: raw, mzXML, or peak
SAMPLE_NO: a sample id
MODE: pos, or neg
Example /api/dl /peak /01026 /pos
Status Deprecated (version 1.4.0 or later)
Description File download is performed. Binary raw data (raw), mass chromatogram data converted into mzXML format (mzXML), and a set of peak list and MS spectra data (peak) are available for each sample analyzed in positive and negative modes.