BioCyc MetaCyc EcoCyc HumanCyc BsubCyc YeastCyc Algae and Cyanobacteria Helicobacter pylori Listeria monocytogenes Mycobacterium tuberculosis Peptoclostridium difficile Pseudomonas aeruginosa Salmonella enterica Shigella flexneri Vibrio cholerae
Information Academic Download
Login/Account Help Searching Intro to BioCyc Website User Guide Webinars Glossary PGDB Concepts Guide Guide to BioCyc Contact Us/Licensing/Support
Current Database:   
Search in Current Database: 

News

News
Update History

Information

Introduction to BioCyc
19493 Databases
Guided Tour
Pathway Tools Software
Pathway Tools Blog
Publications
Linking to BioCyc
Webinars
Contact Us

Services

Subscribe to BioCyc
Metabolic Posters
Genome Posters
Software/Database Downloads
Registry
Web Services
Request New BioCyc Genome

BioCyc Web Services

BioCyc offers several classes of REST-based web services that are summarized in the table below. These services include:
  • Data retrieval services that return data in XML, JSON, and/or column-delimited formats (BioCyc data can also be downloaded in a variety of XML and non-XML formats)

  • Visualization services, e.g., to map gene expression data onto pathway diagrams

  • Services for manipulating SmartTables
Use of the BioCyc web services API is subject to the terms of the BioCyc Databases Limited Use License. Note that to avoid congestion on the BioCyc web servers, we respectfully request that when writing programs that issue large numbers of web service queries, you limit requests to on average not more than one per second.

Class of Service Service Input Output HTTP GET or POST
Retrieve a Single PGDB Object BioCyc object retrieval
 BioCyc Object ID ptools-XML GET
Search and Retrieve a Set of Objects
Data Retrieval Web Services BioCyc Object ID BioPAX XML GET
Foreign object-ID (external database identifier) retrieval Foreign database ID tab delimited file or JSON file GET, POST
Retrieve object sets, e.g., genes-of-pathway, compounds-of-pathway BioCyc Object ID ptools-XML GET
Evaluate query written in BioVelo query language BioVelo Query Object set encoded as ptools-XML
Metabolite monoisotopic weight retrieval Monoisotopic MW, tolerance tab delimited, JSON GET, POST
Metabolite chemical formula retrieval Chemical Formula tab delimited, JSON GET, POST
Metabolite Translation Service tab delimited GET, POST
Visualization Web Services Generate Compound Image Compound ID GIF image GET
Generate Pathway Image Pathway ID GIF image GET, POST
Generate Pathway Page Overlayed with Omics Data Pathway ID HTML GET, POST
Generate Table of Pathway Diagrams Overlayed with Omics Data Pathway ID HTML GET, POST
Highlight Objects on the Cellular Overview Diagram Object Names and / or IDs HTML GET
Display Omics Data from a URL on the Cellular Overview Diagram Object Names and / or IDs HTML GET
SmartTables
SmartTable Creation POST
SmartTable Retrieval tab delimited, JSON, csv GET
SmartTable Add Transform Column GET
SmartTable Add Property Column GET
SmartTable Add Empty Row GET
SmartTable Delete Row GET
SmartTable Add Empty Column GET
SmartTable Delete Column GET
SmartTable Modify Cell POST
SmartTable Modify Name GET
SmartTable Modify Description GET
SmartTable Copy GET
SmartTable Delete GET

Data Retrieval Web Services: Pathway Tools XML

Any pathway, reaction, compound, gene, protein, RNA or transcription-unit object in a BioCyc database can be retrieved in ptools-xml format, an XML format that is based on and closely resembles the underlying Pathway Tools schema. A single object can be requested using its BioCyc identifier, or a query can be issued using either a subset of the Pathway Tools API functions or the BioVelo query language to retrieve multiple objects.

The following documents will be useful in interpreting the ptools-xml format:

The Pathway Tools Schema Guide A guide to the internal Pathway Tools representation, describing classes and their slots (attributes).
Guide to ptools-xml This document describes the ptools-xml format and the differences between ptools-xml and the Pathway Tools Schema, including the mapping of class and slot names from one to the other.
ptools-xml.xsd An XMLSchema document describing the ptools-xml format
ptools.wsdl A WSDL document describing the ptools-xml-based web services.

Retrieve a Single BioCyc Object

Biocyc KB-Version Retrieval

This service finds the version of the KB and returns the result in JSON format.

The URLs for retrieving the KB-version is

https://websvc.biocyc.org/kb-version?orgid=[ORGID]

where

  • [ORGID] is the identifier for the organism database, e.g. ECOLI, META, BSUB.

Example URLs:

The default output is a JSON format as follows:

{"kb-version":"19.5"}

Biocyc Object-Id-Based Retrieval of XML Data

The URL to access a single BioCyc object in ptools-xml format is

https://websvc.biocyc.org/getxml?[ORGID]:[OBJECT-ID] or
https://websvc.biocyc.org/getxml?id=[ORGID]:[OBJECT-id]&detail=[none|low|full]

where

  • [ORGID] is the identifier for the organism database, e.g. ECOLI, META, AFER243159.
  • [OBJECT-ID] is in the BioCyc identifier for the object, e.g. ARGSYN-PWY, EG11025, FRUCTOSE-6P. Note that object identifiers are case-sensitive.
  • [none|low|full] indicates whether the returned output should contain no detail, low detail or full detail for the requested object. If no detail parameter is supplied, the request defaults to full detail.

Example URLs:

Search and Retrieve a Set of Objects

Retrieving a Set of Objects Using the Pathway Tools API Functions

The set of Pathway Tools API functions were defined to allow users who have downloaded and installed the Pathway Tools software locally (why do this?) to write programs that operate on the data. A subset of these API functions have been made available via the web services interface.

The URL to issue an API query that returns a list of objects in ptools-xml format is

https://websvc.biocyc.org/apixml?fn=[API-FUNCTION]&id=[ORGID]:[OBJECT-ID]&detail=[none|low|full]

where [ORGID], [OBJECT-ID] and detail level are as for the single object queries described above, and [API-FUNCTION] is one of the following:

  • all-products-of-gene
  • binding-site-transcription-factors
  • chromosome-of-gene
  • compounds-of-pathway
  • containers-of
  • containing-tus
  • direct-activators
  • direct-inhibitors
  • enzymes-of-gene
  • enzymes-of-pathway
  • enzymes-of-reaction
  • genes-of-pathway
  • genes-of-protein
  • genes-of-reaction
  • genes-regulated-by-gene
  • genes-regulating-gene
  • modified-containers
  • modified-forms
  • monomers-of-protein
  • pathways-of-compound
  • pathways-of-gene
  • reactions-of-compound
  • reactions-of-enzyme
  • reactions-of-gene
  • regulator-proteins-of-transcription-unit
  • regulon-of-protein
  • substrates-of-reaction
  • top-containers
  • transcription-unit-activators
  • transcription-unit-binding-sites
  • transcription-unit-genes
  • transcription-unit-inhibitors
  • transcription-unit-mrna-binding-sites
  • transcription-unit-promoter
  • transcription-unit-terminators
  • transcription-unit-transcription-factors
  • transcription-units-of-gene
  • transcription-units-of-protein

A more detailed description of each API function is available here.

Example URLs:

Retrieving the Set of Objects Returned by a BioVelo Query

The URL to issue a BioVelo query that returns a list of objects in ptools-xml format is

https://websvc.biocyc.org/xmlquery?[QUERY] or
https://websvc.biocyc.org/xmlquery?query=[QUERY]&detail=[none|low|full]

where

  • [QUERY] is a properly escaped BioVelo query string that returns a single list of Pathway Tools objects (it is possible to create BioVelo queries that return multi-column tables -- these are not appropriate as input for this web service). For more information about constructing BioVelo queries, see the Guide to the BioVelo Query Language.
  • [none|low|full] indicates whether the returned output should contain no detail (i.e. only object identifiers and links will be included), low detail (names and a handful of other attributes will be included) or full detail for the matching objects. If no detail parameter is supplied, the request defaults to low detail.

NOTE: the BioVelo query needs to be URL encoded if it contains any non-alphanumeric characters. You might look here, or here if you are unfamiliar with URL encoding.

Example URLs:

Data Retrieval Web Services: BioPAX XML

Pathway data for an individual pathway are available in BioPAX format (both BioPAX Level 2 and Level 3). The URL to access a pathway in BioPAX format is:

https://websvc.biocyc.org/[ORGID]/pathway-biopax?type=[2|3]&object=[PATHWAY]

where

  • [ORGID] is the identifier for the organism database, e.g. ECOLI, META, AFER243159
  • [2|3] specifies whether data should use BioPAX Level 2 or Level 3. If the type argument is omitted, BioPAX Level 3 will be generated.
  • [PATHWAY] is in the BioCyc identifier for the pathway, e.g. GLYCOLYSIS, ARGSYN-PWY, PWY0-1299

Example URLs:

Retrieving a BioCyc Object Given a Foreign ID

This service finds the BioCyc ID of an object given a foreign ID, that is, an identifier of that object in an external database. This service depends on the foreign ID being stored in the DB-Links slot of a BioCyc object. All DB-Links in a given PGDB are searched. Example foreign IDs: Uniprot IDs (P11509) for proteins; KEGG IDs (C00033) for compounds, etc.; Rhea IDs (10743) for reactions.

BioCyc objects such as pathways, reactions, compounds, genes, proteins, RNAs, or transcription-units in a PGDB can be retrieved given a foreign identifier that matches that object.

The URLs to search for objects based on foreign identifier are

https://websvc.biocyc.org/[ORGID]/foreignid?ids=[DATABASE-NAME]:[FOREIGNID] or
https://websvc.biocyc.org/[ORGID]/foreignid?ids=[DATABASE-NAME]:[FOREIGNID]&fmt=json

where

  • [ORGID] is the identifier for the organism database, e.g. ECOLI, META, AFER243159.
  • [DATABASE-NAME] is the name of external database, e.g. KEGG, PUBCHEM, UNIPROT.
  • [FOREIGNID] is the external database identifier. The foreignid input may contain one or more values, which may be separated by commas. Note that foreignids are case-sensitive.
  • fmt=json requests output in the JSON format; default output is in tab-delimited format.
This web service can be used if the user is retrieving the results by either the "POST" or "GET" method.

Example URLs:

The default output is a tab-delimited format as follows: 

Kegg:C00849	1	ETHYLACETATE
EcoGene:EG11025	1	EG11025

where

column 1 : Input Foreign ID.
column 2 : 1 means that a valid object that matches the foreign ID was found and 0 means that no object that matches the foreign ID was found.
column 3 : The BioCyc identifier of the object that matches the foreign ID.

JSON format:

[{"INPUT":"UniProt:P05653","STATUS":1,"RESULTS":[{"ID":"BSU00070-MONOMER"}]}]

Retrieving a BioCyc Object Given a Chemical Formula

This service finds the BioCyc IDs of all metabolites that exactly match a supplied chemical formula. This service consults the Chemical-Formula slot of BioCyc compounds.

The URLs to search metabolites based on chemical formula are

https://websvc.biocyc.org/[ORGID]/CF?cfs=[CHEMICAL-FORMULA] or
https://websvc.biocyc.org/[ORGID]/CF?cfs=[CHEMICAL-FORMULA]&fmt=json

where

  • [ORGID] is the identifier for the organism database, e.g. ECOLI, META, AFER243159.
  • [CHEMICAL-FORMULA] is the chemical formula to be matched, in the format ([element-symbol][coefficient])+. The chemical formula input may contain one or more values, which may be separated by commas. The search will return all metabolites in the specified database that have the exact chemical formula(s) provided here.
  • fmt=json requests output in JSON format; default output is in tab-delimited format
This web service can be used if the user is retrieving the results by either the "POST" or "GET" method. If multiple Chemical formulas are provided than this web service will search for compounds matching each of the chemical formula.

Example URLs:

The default output is a tab-delimited format as follows: 

C6H6	1	BENZENE		benzene
H3O3	0

where

column 1 : Input Chemical Formula.
column 2 : 1 means that a valid compound that matches the chemical formula was found; 0 means that no match was found.
column 3 : The BioCyc identifier of the compound that matches the chemical formula.
column 4 : The common-name of the compound.

JSON format:

[{"INPUT":"H2O2","STATUS":1,"RESULTS":[{"ID":"HYDROGEN-PEROXIDE","NAME":"hydrogen peroxide"}]},{"INPUT":"H3O3","STATUS":0}]

Retrieving a BioCyc Compound given a Monoisotopic Weight and Tolerance

Compounds in a PGDB can be retrieved given a monoisotopic molecular weight and tolerance.

The URLs to search for compounds based on monoisotopic molecular weight and tolerance are

https://websvc.biocyc.org/[ORGID]/monoisotopicwt?wts=[MONOISOTOPICMW]&tol=[TOLERANCE] or
https://websvc.biocyc.org/[ORGID]/monoisotopicwt?wts=[MONOISOTOPICMW]&tol=[TOLERANCE]&fmt=json

where

  • [ORGID] is the identifier for the organism database, e.g. ECOLI, META, AFER243159.
  • [MONOISOTOPICMW] is a floating point number, standing for the monoisotopic molecular weight in daltons. One or more monoisotopic molecular weights can be supplied, where multiple values are separated by commas.
  • [TOLERANCE] is the search tolerance +/- in ppm.
  • fmt=json requests output in the JSON format; default output is in tab-delimited format
This web service can be used if the user is retrieving the results by either the "POST" or "GET" method.

Example URLs:

The default output is a tab-delimited format as follows: 

123.009	1	123.008705	3-chloro-L-alanine	CHLORALAN-CPD
123.009	1	123.008705	3-chloro-D-alanine	3-CHLORO-D-ALANINE
123.009	1	123.008705	2-chloro-L-alanine	CPD0-1475
123.009	1	123.008705	3-chloro-DL-alanine	3-CHLORO-DL-ALANINE
56	0

where

column 1 : Input monoisotopic molecular weight for this search.
column 2 : 1 means the query was successful and 0 means the query found no match.
column 3 : Monoisotopic molecular weight of the compound that is stored in the PGDB
column 4 : Compound name
column 5 : The BioCyc identifier of the compound.

JSON format:

[{"INPUT":"123.009","STATUS":1,"RESULTS":[{"MW":123.008705,"NAME":"3-chloro-L-alanine","ID":"CHLORALAN-CPD"},{"MW":123.008705,"NAME":"3-chloro-D-alanine","ID":"3-CHLORO-D-ALANINE"},{"MW":123.008705,"NAME":"2-chloro-L-alanine","ID":"CPD0-1475"},{"MW":123.008705,"NAME":"3-chloro-DL-alanine","ID":"3-CHLORO-DL-ALANINE"}]},{"INPUT":"56","STATUS":0}]

Metabolite Translation Service

This web service translates metabolite names, identifiers, InChI strings, InChI keys, monoisotopic molecular weights, and molecular formula, between metabolite databases. Its input is a set of lines, one line per metabolite. Each line of the file contains one or more metabolite names, identifiers, and an optional InChI string, InChI key, monoisotopic molecular weight, and chemical formula. The service looks up each of the preceding fields within the specified BioCyc database. Three cases are possible for each line:

    1) None of the provided fields is recognized in the specified BioCyc database, in which case "unknown" is returned, along with the unknown input fields.

    2) All of the recognized names, identifiers, InChI string, InChI key, monoisotopic weight, and chemical formula match a single metabolite, in which case "successful" is returned, along with the following tab-separated fields:

    • BioCyc ID of matching metabolite
    • BioCyc common name of matching metabolite
    • Additional identifiers present in BioCyc from other databases for the matching metabolite

    3) The recognized names, identifiers, InChI string, InChI key, monoisotopic weight, and chemical formula match more than one metabolite, in which case "ambiguous" is returned, along with the ambiguous fields from the input.

The default input for the file or for pasting data is a tab-delimited format.

Example: 

Kegg:C00001	PubChem:125
TRP
ACET

The default output is a tab-delimited format as follows: 

ambiguous	BioCyc:WATER		BioCyc:4-HYDROXY-BENZYL-ALCOHOL	
success		BioCyc:TRP	L-tryptophan	MetaboLights:MTBLC57912	HMDB:HMDB00929	IAF1260:33772	ChEBI:57912	PubChem:6923516	KEGG:C00078	CAS:73-22-3
success		BioCyc:ACET	acetate		MetaboLights:MTBLC30089	HMDB:HMDB00042	DrugBank:DB03166	IAF1260:33590	ChemSpider:170	PubChem:175	ChEBI:30089	CAS:64-19-7	KEGG:C00033	CAS:71-50-1

To access the metabolite translation service interactively, click here

Visualization Web Services

Generate Compound Images

Compound images may be retrieved in GIF format for incorporation into other pages. The basic URL to retrieve a compound image is:

https://websvc.biocyc.org/[ORGID]/diagram-only?type=COMPOUND&object=[COMPOUND]

where

  • [ORGID] is the identifier for the organism database, e.g. ECOLI, META, AFER243159
  • [COMPOUND] is in the BioCyc identifier for the compound, e.g. TRP, CPD-560

Example URL:

Generate Pathway Image GIFs

Pathway images may be generated in GIF format for incorporation into other pages. These images are fully customizable as to the level of detail and which elements are included in the diagrams. URLs to generate a pathway image are of the form:

https://websvc.biocyc.org/[ORGID]/diagram-only?type=PATHWAY&object=[PATHWAY]&[PARAMETER]=[VALUE]

where

  • [ORGID] is the identifier for the organism database, e.g. ECOLI, META, AFER243159
  • [PATHWAY] is in the BioCyc identifier for the pathway, e.g. GLYCOLYSIS, ARGSYN-PWY, PWY0-1299
  • Multiple parameter/value pairs can be specified

The following parameters provide customization options for the pathway diagrams:

Parameters to Customize Pathway Appearance
Parameter Name Possible Values Description Default
detail-level 0,1,2,3,4 Specifies the general detail level for the pathway. The specific elements shown or hidden can be individually overridden using the other parameters below.
0 - Minimal detail, only start/end/branchpoint metabolites shown
1 - All main compounds (those along the main pathway backbone)
2 - All main and side compounds, enzyme and gene names, and EC#s
3 - Compound structures for most main compounds
4 - Compound structures for most main and side compounds 		0, 1 or 2, depending on the size and complexity of the individual pathway.
enz y, n Should enzyme names be shown? Depends on detail level
gene y, n Should gene names be shown? Depends on detail level
ec y, n Should EC numbers be shown? Depends on detail level
secs y, n Should side compounds be shown? Depends on detail level
mstruct none, most, all Should compound structures for main compounds be shown? When most is selected, structures for some very common compounds, such as ATP, NAD, etc. are omitted. none or most, depending on detail level
sstruct none, most, all Should compound structures for side compounds be shown? When most is selected, structures for some very common compounds, such as ATP, NAD, etc. are omitted. none or most, depending on detail level
reglinks y, n If n, omit enzyme regulation icons and feedback inhibition links y
nolinks y, n If y, suppress showing links to other pathways n
pfontsize tiny, very-small, small, normal, large, very-large Font size used in diagram very-small
bgcolor w, cb, g, bw, tr The color scheme for the diagram:
w: Colors on a white background
cb: Colors on a black background
g: Colors on a gray background
bw: Black on a white background
tr: Same colors as for w, but on a transparent background 		tr
linear snake, horizontal, vertical Specify whether linear pathways are drawn horizontally, vertically, or in a horizontal back-and-forth "snake"-like fashion. Note that only pathways that contain no cycles or branchpoints (including branchpoints resulting from links to/from other pathways) are recognized as linear pathways and therefore sensitive to this parameter. snake

Example URLs:

Generate Individual Pathway Images Overlayed with Omics Data

Pathway pages can be displayed with omics data superimposed on the pathway diagrams. This operation navigates to the web page for the requested pathway. URLs to generate a pathway web page with overlayed omics data are of the form:

https://websvc.biocyc.org/[ORGID]/new-image?type=PATHWAY&object=[PATHWAY]&[PARAMETER]=[VALUE]

where

  • [ORGID] is the identifier for the organism database, e.g. ECOLI, BSUB, AFER243159
  • [PATHWAY] is in the BioCyc identifier for the pathway, e.g. GLYCOLYSIS, ARGSYN-PWY, PWY0-1299
  • Multiple parameter/value pairs can be specified, but two are required in order to show omics data:
    • url (for GET) or datafile (for POST)
    • column1

The table below outlines the possible paramaters that control the mapping of omics data to pathway diagrams, as well as on the cellular overview diagram (see the next section). In addition, the options detailed in the previous table can be used to customize the rendering of the pathway itself.

The omics data can be supplied in two possible ways: as a POST request (which allows the omics data to be private), and by making the data available on a publicly accessible web server.

Parameters to Customize Pathway and Cellular Overview Omics-Data Visualizations
Parameter Name Possible Values Pathway (P), Table (T) or Cellular Overview (O) Description Default
datafile A filename P, T This parameter is REQUIRED for a POST, and should not be used for a GET. Its value should be a filename.
The file should be tab-delimited, the first column (often referred to as Column 0) being the id of the gene/protein/compound/reaction/other to which the data in the remaining columns applies.		 REQUIRED
for POST
no default
url An example file supplied by the website administrator P, T, O This parameter is REQUIRED for a GET, and should not be used for a POST. Its value used to be a URL that points to a data file, but now, for security reasons, is limited to naming an example file supplied by the website administrator. REQUIRED
for GET
no default
class gene, protein, compound, reaction, 'NIL' P, T, O gene Gene names and/or identifiers
protein Protein names and/or identifiers
compound Compound names and/or identifiers
reaction Reaction identifiers and/or EC numbers
'NIL' Any of the above

The given value declares the type(s) of the id's found in column 0 (the first column) of the data file. 		gene
column1 numbers separated by space or comma AND/OR,
range of numbers (number pair separated by hyphen)		 P, T, O data columns from datafile to be painted on pathway graphic (e.g. &column1=4-7 9 would select data from columns 4, 5, 6, 7, and 9 in each row of the file.) REQUIRED
no default
expressiontype relative, absolute P, T, O relative: the numerical data represents a ratio (relative to some other dataset or to a control) and is therefore centered around either 0 or 1 (see log parameter below).
absolute: the numerical data represents absolute values, e.g. intensities or concentrations, and are all non-negative.		 relative
log on, off P, T, O on: 0-centered data
off: 1-centered data
  • 0-centered scale: implies that the numerical data of your file can contain positive and negative values. The value 0 is considered to be the center of the numerical values provided in your data file.
  • 1-centered scale: implies that any negative or zero values in your data file should be skipped. Moreover, the data is centered around the value 1 using a log scale. For example, the value 0.1 is considered to be at the same distance to 1 as the value 10. So, a logarithm of base 10 is applied to your data before the linear coloring mapping is applied.
 on
color default, specify, rbg, rbg-cutoff, 3-color P, T, O
  • default : Orange to gray to blue from data
  • specify : Orange to gray to blue with a maximum cutoff (maxcutoff parameter detailed in this table)
  • rbg : Red to green from data
  • rbg-cutoff : Red to green with a maximum cutoff (maxcutoff parameter detailed in this table)
  • 3-color : Three-color display with a threshold
Data values are divided into color bins. You can choose between a color scheme that ranges from orange (most positive values) through gray in the center to blue (most negative values) or from red through blue in the center to green and yellow. For each of these color schemes, two options are available:
  • The color bins range over the entire spectrum, and the cutoff values for the color bins are derived from the data itself. This means that different experiments could be displayed using different color schemes, making it difficult to directly compare them.
  • You may specify a value for the maximum value cutoff (maxcutoff parameter) bin. All displays that use the same maximum value cutoff will use the same color scheme (assuming other settings are the same), and are therefore directly comparable. The maximum cutoff value should be a number, e.g. 2 or 10, etc. All data values greater than the maximum cutoff value will be displayed in the highest bin color.
A final alternative is to use only three color bins, red for data values that exceed some threshold (see parameter below), purple for data values less than the inverse of that threshold, and gray for values in between. The threshold value should be a number, e.g. 2 or 10.		 default
threshold a numeric value P, T, O Required if 3-color specified. See discussion in 'color' parameter section of this table. no default
maxcutoff a numeric value P, T, O Required if specify or rbg-cutoff specified. See discussion in 'color' parameter section of this table. no default
omicsPopups on, unspecified P If present, display the omics data in popup windows, usually one popup per reaction or metabolite in the pathway. This is the only way to show data in multiple columns. A single column of data can either be shown in popups or (if unspecified) as color coded buttons on the diagram. unspecified
defaultPopup bar, plot, heat P The style of data display in the omics popups: a bar graph, an x-y plot, or a heat map. bar

A single column of gene data from the file displayed with colored "buttons":

A single column of gene data from the file displayed with popups:

Five columns of compound (metabolomics) data from the file displayed with popups and heat map as default popup style:

Generate a Table of Pathway Diagrams Overlayed with Omics Data

This operation navigates to a web page containing a table of low-detail pathway diagrams, colored to show omics data values. To submit data via the HTTP GET method, use the following URL format:

https://websvc.biocyc.org/[ORGID]/overview-expression-map?pathways=[PATHWAYS]&[PARAMETER]=[VALUE]

where

  • [ORGID] is the identifier for the organism database, e.g. ECOLI, BSUB, AFER243159
  • [PATHWAYS] is a comma-separated list of BioCyc identifiers for the desired pathways, e.g. GLYCOLYSIS, ARGSYN-PWY, PWY0-1299
  • Multiple parameter/value pairs can be specified. If none are specified, then the table will be generated without omics data.

The list of available parameters are those marked T in the above Omics Data Parameters Table. The pathway diagrams cannot be customized, and any pathway customization parameters will be ignored. This view is more useful for gene expression data than for metabolomics data, as any side metabolites will not be visible on the pathway diagrams. Popups are also not available with this view -- if multiple data columns are specified, the resulting table will contain a column of pathway diagrams for each data column. The same URL and parameters are used for GET and POST queries except that GET queries must supply the url parameter and POST queries must supply the datafile parameter to upload data from a local file.

Example URL:

Cellular Overview Visualization Services

The following services all navigate to a web page containing the cellular overview (metabolic map) diagram with the specified data overlays.

Highlight Objects on the Cellular Overview Diagram

Objects can be specified for highlighting by name, ID or substring. URLs to highlight specified objects are of the form:

https://websvc.biocyc.org/overviewsWeb/celOv.shtml?orgid=[ORGID]&zoomlevel=[0-4]&[OP]=[VALUE]

where

  • [ORGID] is the identifier for the organism database, e.g. ECOLI, BSUB, AFER243159
  • zoomlevel [0-4] is an integer that indicates the extent to which the diagram has been zoomed. The lowest zoom level is 0 (smallest overview) and the highest is 6 (largest Overview). If not supplied, the zoomlevel defaults to 0.
  • [OP] specifies a highlighting operation and [VALUE] is a name, ID or substring to be highlighted. Multiple highlighting operations can be specified in a single URL. The possible highlighting operations are described in the following table. Note that all these operations correspond to the operations available from the top menu bar when a Cellular Overview diagram is displayed. The operation xnids is special as it accepts data values as well. A data value can be specified after each name.
    Op Highlight Operation
    rnids Highlight reaction names or frame ids.
    rsubs Highlight reaction substrings.
    recns Highlight reaction EC numbers.
    pnids Highlight pathway names or frame ids.
    psubs Highlight pathway substrings.
    gnids Highlight gene names or frame ids.
    gsubs Highlight gene substrings.
    enids Highlight enzyme names or frame ids.
    esubs Highlight enzyme substrings.
    cnids Highlight compound names or frame ids.
    csubs Highlight compound substrings.
    xnids Highlight a mix of names and frame ids with or without omics data.
    pcids Highlight pathways based on curation status.
    rcids Highlight reactions based on curation status.
    revis Highlight reactions based on evidence selected.
    pevis Highlight pathways based on evidence selected.
    gregs Highlight genes based on regulation selected.
    greps Highlight genes based on replicons.

The string specified after the ‘=’ for an operation must not be quoted, and any special characters must be URL encoded. The string is not case-sensitive. Multiple values separated by commas may be supplied for any of the above operations (except xnids, which uses URL-encoded spaces as separators). There is no difference between suppling multiple comma-separated values for a single operation versus specifying that operation multiple times, once for each value. When supplying omics data values using the xnids operation, the id and the value should be separated by a URL-encoded space. If multiple objects are specified using the xnids operation, either all must have data values (resulting in an omics viewer display), or any data values will be ignored (reverting to a basic highlighting operation).

Example URLs:

These URLs with highlighting operations can be automatically generated by applying the desired highlights using the GUI, and then right-clicking on the diagram and selecting the command Generate Bookmark for Current Cellular Overview.

Display Omics Data on the Cellular Overview Diagram via a URL

The Omics Viewer can be invoked by using a URL link that specifies an omics data file that resides on a publicly accessible website. See the Omics Viewer section of the Website Users Guide for more information about the Omics Viewer, including the data file format. This GET request will navigate to the Cellular Omics Viewer page and load it with data from the supplied URL and the parameters specified in the request itself.

URLs to paint omics data on the cellular overview diagram are of the form:

https://websvc.biocyc.org/overviewsWeb/celOv.shtml?orgid=[ORGID]&omics=t&zoomlevel=[0-4]&[PARAMETER]=[VALUE]

where

  • [ORGID] is the identifier for the organism database, e.g. ECOLI, BSUB, AFER243159
  • zoomlevel [0-4] is an integer that indicates the extent to which the diagram has been zoomed. The lowest zoom level is 0 (smallest overview) and the highest is 6 (largest Overview). If not supplied, the zoomlevel defaults to 0.
  • Multiple parameter/value pairs can be specified, but two are required:
    • url
    • column1
The list of available parameters are those marked O in the Omics Data Parameters Table.

Example URLs:

SmartTables

SmartTable Retrieval

SmartTable data can be accessed from a web service in the following formats: JSON, XML, or tab delimited. This web service will request your account username and password.

The basic URL to retrieve a SmartTable is:

https://websvc.biocyc.org/st-service-get?id=[SMARTTABLE-ID]&format=[json|xml|tsv]

where

  • [SMARTTABLE-ID] is the identifier of the SmartTable, e.g. biocyc11-2762-3605383628, biocyc10-NIL-3608637901
  • [json|xml|tsv] is the requested format for the SmartTable data. json will return the data in JSON format, xml in XML format, and tsv in tab delimited format.

An example of the JSON structure can be found in the JSON Structure for SmartTables Retrieval and Creation.

Example URL:

SmartTable Creation

To create a SmartTable from data supplied via a file using the web service URL, the user must use a tool that can peform a "PUT" method. The result returned will contain the identifier of the created SmartTable. curl will be used for examples in this documentation section. When using curl, the terminal command may look like the following:

curl -u '[USER@DOMAIN.COM]' -X PUT -T [ST-PATH] http://localhost:1555/st-service-create?id=[ID]&format=[json|xml|tsv]

where

  • [USER@DOMAIN.COM] is the user's email address associated with their account
  • [ST-PATH] is the local path to the file containing SmartTable data, e.g. /tmp/test-st
  • [json|xml|tsv] is the data format of the SmartTable data stored at [st-path]
  • [ID] (optional) is the identifier for the SmartTable

Example terminal command:

  • curl -u 'USER@DOMAIN.COM' -X PUT -T /tmp/test-st.xml http://www.biocyc.org/st-service-create?format=xml

JSON Structure for SmartTable Retrieval and Creation

JSON file structure:

  • name (optional) - name field of SmartTable
  • description (optional) - description field of SmartTable
  • Contents of the short form, which is for creating a single column of values only:
    • type: an object class that values will be coerced into for the given database into the SmartTable
    • pgdb: an org id for the database in which SmartTable objects will reside and be coerced with the given type
    • values: an array of strings, which will be coerced into objects for the SmartTable in a single column
  • Contents of the long form, which is for creating multiple columns of values:
    • columns: a list (JSON array) of columns, each of which is:
      • name (optional): a string that will be the name of the column
      • type: an object class that values will be coerced into for the SmartTable
    • rows: a JSON array, each element is a dictionary mapping column ids to values. Each value corresponds to one cell in the SmartTable and contains:
      • value: a string, number, or {frameid: , pgdb: } which will be coerced into an object for the SmartTable

JSON examples: 

// Short form
{"name": "sample short-form group",
 "description": "sample short-form description",
 "pgdb": "ECOLI",
 "type": "Genes",
 "values": ["trpA", "trpB"]
}

// long form (2 columns)
{"name": "sample long-form group",
 "description": "This is a longer form of JSON used with a SmartTable.",
 "columns": [{"name": "Gene",
                      "type": "Genes"},
                    {"name": "Expression Level"}]
 "rows": [{{"frameid": "EG11204", "pgdb": "ECOLI"},
                 "1.3"}
      {{"frameid": "EG11205", "pgdb": "ECOLI"},
        "-2.2"}]
}

XML Structure for SmartTable Retrieval and Creation

The XML file structure follows a similar structure to the JSON format. The following is the XML schema: 

<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="GROUP">
    <xs:complexType>
      <xs:attribute type="xs:string" name="ID"/>
      <xs:attribute type="xs:string" name="NAME"/>
      <xs:sequence>
        <xs:element name="COLUMNS">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="COLUMN" maxOccurs="unbounded" minOccurs="1">
                <xs:complexType>
                  <xs:simpleContent>
                    <xs:extension base="xs:string">
                      <xs:attribute type="xs:string" name="NAME" use="optional"/>
                      <xs:attribute type="xs:string" name="TYPE" use="optional"/>
                    </xs:extension>
                  </xs:simpleContent>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="ROWS">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="ROW" maxOccurs="unbounded" minOccurs="0">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element name="CELL" maxOccurs="unbounded" minOccurs="0">
                      <xs:complexType mixed="true">
                        <xs:sequence>
                          <xs:element name="FRAME" maxOccurs="unbounded" minOccurs="0">
                            <xs:complexType>
                              <xs:simpleContent>
                                <xs:extension base="xs:string">
                                  <xs:attribute type="xs:string" name="ID" use="optional"/>
                                  <xs:attribute type="xs:string" name="PGDB" use="optional"/>
                                </xs:extension>
                              </xs:simpleContent>
                            </xs:complexType>
                          </xs:element>
                          <xs:element type="xs:string" name="VALUE" maxOccurs="unbounded" minOccurs="0"/>
                        </xs:sequence>
                      </xs:complexType>
                    </xs:element>
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

XML example: 

<GROUP ID="biocyc14-2762-3579243971" NAME="Import from snp.txt">

  <COLUMNS>
    <COLUMN NAME="Position" TYPE="NUMBER"/>
    <COLUMN NAME="Gene" TYPE="All-Genes"/>

    <COLUMN
     NAME="Map to Alicyclobacillus acidocaldarius acidocaldarius DSM 446"
     TYPE="All-Genes"/>
    <COLUMN NAME="new column"/>

    <COLUMN NAME="Binding sites upstream of gene" TYPE="DNA-Binding-Sites"/>
  </COLUMNS>

  <ROWS>

    <ROW>
      <CELL><VALUE>10</VALUE></CELL>
      <CELL><FRAME ID="EG11024" PGDB="ECOLI"/></CELL>
      <CELL><FRAME ID="GCIO-1719" PGDB="AACI521098"/></CELL>
      <CELL/>

      <CELL>
        <FRAME ID="BS00206" PGDB="ECOLI"/>
        <FRAME ID="BS0-4061" PGDB="ECOLI"/>
        <FRAME ID="BS0-4062" PGDB="ECOLI"/>
      </CELL>
    </ROW>
  </ROWS>
</GROUP>

Other SmartTable Web Services

Various operations to manipulate existing SmartTables can be done with the following web services.

Service Name Arguments HTTP POST or GET Example Description
st-service-transform id, transformationid, index
 GET https://websvc.biocyc.org/st-service-transform?id=biocyc11-2762-3605383628&transformid=compound-producing-pathways&index=0 Adds a transformation column to an existing SmartTable.

id: SmartTable identifier
transformationid: Name of the transformation to use. See This table for available transformations.
index: Column number to base the new transformation column on. First column starts with 0.
st-service-property id, propertyid, index
 GET https://websvc.biocyc.org/st-service-property?id=biocyc11-2762-3605383628&propertyid=common-name&index=0 Adds a slot property column to an existing SmartTable.

id: SmartTable identifier
propertyid: Name of the slot to use.
index: Column number to base the new transformation column on. First column starts with 0.
st-service-add-row id
 GET https://websvc.biocyc.org/st-service-add-row?id=biocyc11-2762-3605383628 Adds an empty row to an existing SmartTable.

id: SmartTable identifier
st-service-delete-rows id, indices
 GET https://websvc.biocyc.org/st-service-delete-rows?id=biocyc11-2762-3605383628&indices=0,1 Deletes rows from an existing SmartTable.

id: SmartTable identifier
indices: Row numbers to delete. First row starts with 0.
st-service-add-column id
 GET https://websvc.biocyc.org/st-service-add-column?id=biocyc11-2762-3605383628 Adds an empty column to an existing SmartTable.

id: SmartTable identifier
st-service-delete-column id, index
 GET https://websvc.biocyc.org/st-service-delete-column?id=biocyc11-2762-3605383628&index=0 Deletes a column from an existing SmartTable.

id: SmartTable identifier
index: Column number to delete. First column starts with 0.
st-service-modify-cell id, format, row, column
 POST Adds an empty row to an existing SmartTable.

id: SmartTable identifier
format: Cell body format. Can be XML or JSON. (More on cell body format).
row: Row number of the cell to modify. First row starts with 0.
column: Column number of the cell to modify. First column starts with 0.
st-service-modify-name id, name
 GET https://websvc.biocyc.org/st-service-modify-name?id=biocyc11-2762-3605383628&name=All+Genes Modifies the name of an existing SmartTable.

id: SmartTable identifier
name: SmartTable name text.
st-service-modify-description id, description
 GET https://websvc.biocyc.org/st-service-modify-description?id=biocyc11-2762-3605383628&description=All+Genes+of+Dataset Modifies the description of an existing SmartTable.

id: SmartTable identifier
description: SmartTable description text.
st-service-copy id
 GET https://websvc.biocyc.org/st-service-copy?id=biocyc11-2762-3605383628 Creates a copy of an existing SmartTable.

id: SmartTable identifier
st-service-delete id
 GET https://websvc.biocyc.org/st-service-delete?id=biocyc11-2762-3605383628 Deletes an existing SmartTable.

id: SmartTable identifier