Metabolomics WorkBench REST service

MW REST API (v1.1, 11/27/2023) Download API (pdf)

The Metabolomics WorkBench REST service enables access to a variety of data (including metabolite structures, study metadata and experimental results) using HTTP requests. These requests may be carried out using a web browser or may be embedded in 3rd party applications or scripts to enable programmatic access. Most modern programming languages including PHP, Perl, Python, Java and Javascript have the capability to create HTTP request and interact with datasets such as this REST service.

The REST URL consists of three main parts, separated by forward slashes, after the common prefix specifying the invariant base URL:
(https://www.metabolomicsworkbench.org/rest/)

  1. The context specification dictates which type of resource to access and is chosen from one of the following:
    <study | compound | refmet | metstat | gene | protein | moverz>
  2. The input specification is composed of 2 required parameters separated by forward slashes. The first parameter is the input item which depends on the context. The 2nd parameter is an appropriate input value for the chosen item. Examples of an input specification are:
    /compound/pubchem_cid/311/
    /compound/formula/C20H34O/
    /study/study_id/ST000001/
    /study/study_title/diabetes/
    /refmet/name/Cholesterol/
    /refmet/match/LysoPC16:0/
    /gene/gene_symbol/acaca/
    /protein/uniprot_id/Q13085/
    Exceptions to this input specification occur when the 'moverz' context (MS search) is selected. In this case the input value must consist of 3 parts separated by forward slashes: <m/z value>/<adduct>/<tolerance(Daltons)>, e.g. '635.52/M+H/0.2'. In the case of the 'exactmass' input item the input value must consist of 2 parts separated by forward slashes: <lipid bulk abbreviation>/<adduct>, e.g. 'PC(34:1)/M+H' and the output items are ignored.
  3. The output specification is composed of a required output item parameter and an optional output format parameter. The list of possible output items depends on the value chosen for the context. In the case of the "compound" context one or more (separated by commas) of 'regno', 'formula','exactmass', 'inchi_key', 'name', 'sys_name', 'smiles', 'lm_id', 'pubchem_cid', 'hmdb_id', 'kegg_id', 'chebi_id', 'metacyc_id' may be specified. More conveniently, an output type of 'all' may be specified to retrieve all compound-related fields. Also an output type of 'classification' retrieves the LIPID MAPS/ClassyFire classification hierarchy. In the case of the "study" context, allowed output types are 'summary', 'factors', 'analysis', 'metabolites' and 'data'. The default output format is JSON which is amenable to manipulation and parsing by various programming languages. Optionally a text ouput format may be specified, for example:
    /compound/pubchem_cid/311/all/txt
    Exceptions to this output specification occur when either 'molfile' (molfile is downloaded) or 'png' (png image is displayed in browser) is chosen as an output item in the "compound" context.
    The metstat context has 8 slots delimited by semicolons:
    /rest/metstat/<ANALYSIS_TYPE>;<POLARITY>;<CHROMATOGRAPHY>;<SPECIES>;<SAMPLE SOURCE>;<DISEASE>;<KEGG_ID>;<REFMET_NAME>
    One may skip slots but the semicolons must be entered to ensure that the proper category is assigned to each slot (see examples below).
    See the MetStat form pulldown menus to view allowed items for each category or the Bubble plot lists for species, sample source and disease association.

    The interactive "REST url" creator below shows most of the currently available options for this service.

Base URL /Context /Input item /Input value /Output item /Output format
https://www.metabolomicsworkbench.org/rest / / / / /

(What is REST?) (What is JSON?)

The table below contains several examples of REST urls.

Example request Example URL
Compound context
Fetch compound common name from Metabolomics Workbench database regno https://www.metabolomicsworkbench.org/rest/compound/regno/11/name
Fetch all compound fields from Metabolomics Workbench database regno https://www.metabolomicsworkbench.org/rest/compound/regno/11/all
Fetch all compound fields as text from Metabolomics Workbench database regno https://www.metabolomicsworkbench.org/rest/compound/regno/11/all/txt
Fetch compound smiles from PubChem compound ID https://www.metabolomicsworkbench.org/rest/compound/pubchem_cid/5281365/smiles
Fetch compound common name and sytematic name from InChIKey https://www.metabolomicsworkbench.org/rest/compound/inchi_key/JTWQQJDENGGSBJ-UHFFFAOYSA-N/name,sys_name
Fetch all compound fields from formula (multiple records) https://www.metabolomicsworkbench.org/rest/compound/formula/C20H34O/all
Fetch compound classification hierarchy from PubChem compound ID https://www.metabolomicsworkbench.org/rest/compound/pubchem_cid/5281365/classification
Download compound molfile from Metabolomics Workbench database regno https://www.metabolomicsworkbench.org/rest/compound/regno/34361/molfile
Download compound SD file from Metabolomics Workbench database regno https://www.metabolomicsworkbench.org/rest/compound/regno/34361/sdf
Fetch png image of structure from Metabolomics Workbench database regno https://www.metabolomicsworkbench.org/rest/compound/regno/11/png
Study context
Show all publicly available studies (Project, Study, Analysis ID) https://www.metabolomicsworkbench.org/rest/study/study_id/ST/available
Fetch summary information for a study https://www.metabolomicsworkbench.org/rest/study/study_id/ST000001/summary
Fetch samples and experimental variables (factors) for a study https://www.metabolomicsworkbench.org/rest/study/study_id/ST002115/factors/
Fetch summary information for all studies https://www.metabolomicsworkbench.org/rest/study/study_id/ST/summary
Fetch analysis information for a study https://www.metabolomicsworkbench.org/rest/study/study_id/ST000001/analysis
Fetch metabolites and annotations detected in a study (one study at a time) https://www.metabolomicsworkbench.org/rest/study/study_id/ST000009/metabolites
Fetch metabolites measurements for a study (one study at a time) https://www.metabolomicsworkbench.org/rest/study/study_id/ST000001/data
Fetch mwTab content for an analysis within a study in mwTab format https://www.metabolomicsworkbench.org/rest/study/analysis_id/AN000001/mwtab/txt
Fetch mwTab content for an analysis within a study in json format https://www.metabolomicsworkbench.org/rest/study/analysis_id/AN000001/mwtab
Fetch species information (as text) for all studies https://www.metabolomicsworkbench.org/rest/study/study_id/ST/species/txt
Fetch sample source information (as text) for all studies https://www.metabolomicsworkbench.org/rest/study/study_id/ST/source/txt
Fetch disease association (where applicable) for all studies https://www.metabolomicsworkbench.org/rest/study/study_id/ST/disease
Fetch list of studies with untargeted data in NMDR https://www.metabolomicsworkbench.org/rest/study/study_id/x/untarg_studies/
Fetch untargeted data (where applicable) for an analysis within a study https://www.metabolomicsworkbench.org/rest/study/analysis_id/AN000113/untarg_data/
Fetch experimental factors for an untargeted data analysis within a study https://www.metabolomicsworkbench.org/rest/study/analysis_id/AN000113/untarg_factors/
Fetch list of studies with named metabolites in NMDR https://www.metabolomicsworkbench.org/rest/study/study_id/ST/named_metabolites/
Show number of named metbolites in a study https://www.metabolomicsworkbench.org/rest/study/study_id/ST000001/number_of_metabolites/
Fetch list of studies (as text) containing a RefMet name https://www.metabolomicsworkbench.org/rest/study/refmet_name/Cholesterol/data/txt/
Fetch list of studies (as text) containing a KEGG_ID https://www.metabolomicsworkbench.org/rest/study/kegg_id/C00002/data/txt/
Show metabolite name and RefMet name for a (NMDR) metabolite_id https://www.metabolomicsworkbench.org/rest/study/metabolite_id/ME272191/available/
Fetch table of results (identified metabolites) for an analysis_id https://www.metabolomicsworkbench.org/rest/study/analysis_id/AN000001/datatable/
Download table of results (identified metabolites) for an analysis_id https://www.metabolomicsworkbench.org/rest/study/analysis_id/AN000001/datatable/file
RefMet context
Fetch all RefMet fields from name https://www.metabolomicsworkbench.org/rest/refmet/name/Cholesterol/all
Fetch all RefMet fields from formula https://www.metabolomicsworkbench.org/rest/refmet/formula/C12H24O2/all
Standardize metabolite name to RefMet https://www.metabolomicsworkbench.org/rest/refmet/match/citrate/name/
Fetch entire RefMet database (Name,exact mass,formula,InChIKey,PubChemID,classification) https://www.metabolomicsworkbench.org/rest/refmet/all
Fetch all RefMet records containing external id's (PubChem CID,ChEBI,HMDB,KEGG,LIPID MAPS) https://www.metabolomicsworkbench.org/rest/refmet/all_ids
Fetch all RefMet names https://www.metabolomicsworkbench.org/rest/refmet/name
Fetch all RefMet names and chemical classification https://www.metabolomicsworkbench.org/rest/refmet/classification
MetStat context
Fetch all human studies on blood with a diabetes association run on LCMS using HILIC in positive ion mode https://www.metabolomicsworkbench.org/rest/metstat/LCMS;POSITIVE;HILIC;Human;Blood;Diabetes
Fetch all human studies on blood with a diabetes association (any type of analysis) https://www.metabolomicsworkbench.org/rest/metstat/;;;Human;Blood;Diabetes
Fetch all human studies on blood containing Tyrosine (RefMet name) https://www.metabolomicsworkbench.org/rest/metstat/;;;Human;Blood;;;Tyrosine
Fetch all studies containing Desmosterol (RefMet name) https://www.metabolomicsworkbench.org/rest/metstat/;;;;;;;Desmosterol
Fetch all studies containing KEGG ID C00632 (3-Hydroxyanthranilic acid) https://www.metabolomicsworkbench.org/rest/metstat/;;;;;;C00632
Fetch all mouse studies on brain with Metabolic syndrome association https://www.metabolomicsworkbench.org/rest/metstat/;;;Mouse;Brain;Metabolic syndrome
Gene/protein context
Fetch all gene fields from gene symbolhttps://www.metabolomicsworkbench.org/rest/gene/gene_symbol/acaca/all
Fetch gene name from Entrez gene idhttps://www.metabolomicsworkbench.org/rest/gene/gene_id/31/gene_name
Fetch all protein fields from UniProt idhttps://www.metabolomicsworkbench.org/rest/protein/uniprot_id/Q13085/all
Fetch all protein fields from Entrez gene idhttps://www.metabolomicsworkbench.org/rest/protein/gene_id/19/all/
Fetch mRNA id from protein Refseq idhttps://www.metabolomicsworkbench.org/rest/protein/refseq_id/NP_005493/mrna_id/
moverz(Mass spectrometry) context
Perform MS precursor ion search on Metabolomics Workbench database with m/z 635.52, ion-type* M+H and mass tolerance of 0.5 and output as text https://www.metabolomicsworkbench.org/rest/moverz/MB/635.52/M+H/0.5/txt
Perform MS precursor ion search on LIPIDS virtual database with m/z 513.45, ion-type* M-2H (2-) and mass tolerance of 0.2 and output as text https://www.metabolomicsworkbench.org/rest/moverz/LIPIDS/513.45/M-2H/0.2/txt
Perform MS precursor ion search on RefMet database with m/z 255.2, ion-type* M+H and mass tolerance of 0.2 and output as text https://www.metabolomicsworkbench.org/rest/moverz/REFMET/255.2/M+H/0.2/txt
Calculate the exact mass (m/z) of the [M+H]+ ion of the lipid abbreviation# PC(34:1) https://www.metabolomicsworkbench.org/rest/moverz/exactmass/PC(34:1)/M+H

*Ion-types:
Positive: M+H, M+2H, M+3H, M+4H, M+H-H2O, M+H-Hexose, M+H-EtnP, M+H-SerP, M+H+CH3OH, M+H+CH3CN, M+H+2CH3CN, M+Na+CH3CN, M+NH4, M+Ag, M+Na, M+2Na-H, M+2K-H, M+2Na, M+K, M+2K, M+Li, M+2Li, M.NaFormate-H, M.NaFormate+H, M.NH4Formate-H, M.NH4Formate+H, M., M.CH3
Negative: M-H, M-2H, M-3H, M-4H, M-CH3, M-H-H2O, M.Cl, M.F, M.HF2, M.OAc, M.Formate, M.NaFormate-H, M.KFormate-H, M+Na-2H, M+K-2H, M-H-Ser
Uncharged: Neutral

#Lipid abbreviations:
FA, CoA, CAR, MG, DG, TG, PA, PC, PS, PE, PG, PGP, PI, PIP, PIP2, PIP3, MGDG, DGDG, SQDG, Cer, SM, CerP, PE-Cer, PI-Cer, GlcCer, GalCer, LacCer, GM3Cer, GM4Cer, GB3Cer, iGB3Cer, asialo-GM2Cer, Lc3Cer, Manb1-4GlcCer, MolluCer, ArthroCer, CE
Lipid abbreviation notes: These are sum-composition or "bulk" abbreviations (<total number of carbons in chain(s)>:<total number of double bonds in chain(s)>). Sphingolipid abbreviations must contain a letter prefix indicating number of hydroxyl groups (<m|d|t>), for example, Cer(d34:1) for a ceramide, Cer(t32:0) for a phytoceramide and Cer(m32:1) for a 1-deoxyceramide.

REST (REpresentational State Transfer) is an architectural style consisting of a coordinated set of architectural constraints applied to components, connectors, and data elements, within a distributed hypermedia system. REST ignores the details of component implementation and protocol syntax in order to focus on the roles of components, the constraints upon their interaction with other components, and their interpretation of significant data elements.
Fielding, Roy T. (2000). "Chapter 5: Representational State Transfer (REST)". Architectural Styles and the Design of Network-based Software Architectures (Ph.D.). University of California, Irvine.
Fielding, Roy T.; Taylor, Richard N. (May 2002), "Principled Design of the Modern Web Architecture" (PDF), ACM Transactions on Internet Technology (TOIT) (New York: Association for Computing Machinery) 2 (2): 115-150, doi:10.1145/514183.514185, ISSN 1533-5399
REST Wikipedia page

JSON (JavaScript Object Notation) is a lightweight data-interchange format which human readable and also convenient for computers to parse and generate. JSON is a text format that is completely language independent but uses conventions that are familiar to most common programming languages.
Official JSON website

  logo