Food Metabolome Repository
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. | |
Functions
Displaying the results on a browser
- Displaying peaks searched by a mass value and a retention time
- Displaying peaks searched by a mass value and a retention time (Older version)
- Displaying peaks with MS2 or MS3 spectra searched by a query spectrum
- Displaying peak information
Getting the results in JSON format
- Getting statistics
- Getting a sample list
- Getting a sample list (for published items)
- Getting a peak list detected in a sample
- Getting peak information
- Getting MS spectra for a peak
- Getting peaks searched by a mass value and a retention time
- Getting summary of peaks searched by a mass value and a retention time
- Getting peaks with MS2 or MS3 spectra searched by a query spectrum
- Getting the number of spectra with a specified neutral loss mass
- Getting the spectra with a specified neutral loss mass
- Getting a list of mass chromatogram data (ZIP files) for download
- Getting information of peak data (ZIP file) for download
Getting the images
- Getting a image of 2D chromatogram
- Getting a image of food
- Getting a image of 2D chromatogram with a sample image
Downloading
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. |