MG-RAST API Overview

The MG-RAST API covers most of the functionality available through the MG-RAST website, with access to annotations, analyses, metadata and access to the MG-RAST user inbox to view contents as well as upload files. All sequence data and data products from intermediate stages in the analysis pipeline are available for download. Other resources provide services not available through the website, e.g. the m5nr resource lets you query the m5nr database.

Each query to the API is represented as a URI beginning with "http://api.metagenomics.anl.gov/" and has a defined structure to pass the requests and parameters to the API server.

The URI queries can be used from the command line, e.g. using curl, in a browser, or incorporated in a shell script or program.

Each URI has the form

"http://api.metagenomics.anl.gov/{version}/{resourcepath}?{querystring}"

The {version} value (currently '1') explicitly directs the request to a specific version of the API, if it is omitted the latest API version will be used.

The resource path is constructed from the path parameters listed below to define a specific resource and the optional query string is used to filter the results obtained for the resource. For example:

http://api.metagenomics.anl.gov/1/annotation/sequence/mgm4447943.3?evalue=10&type=organism&source=SwissProt

In this example the resource path "annotation/sequence/mgm4447943.3" defines a request for the annotated sequences for the MG-RAST job with ID 4447943.3.

The optional query string "evalue=10&type=organism&source=SwissProt" modifies the results by setting an evalue cutoff, annotation type and database source.

The API provides an authentication mechanism for access to private MG-RAST jobs and users' inbox. The 'auth_key' (or 'webkey') is a 25 character long string (e.g. 'j6FNL61ekNarTgqupMma6eMx5') which is used by the API to identify an MG-RAST user account and determine access rights to metagenomes. Note that the auth_key is valid for a limited time after which queries using the key will be rejected. You can create a new auth_key or view the expiration date and time of an existing auth_key on the MG-RAST website. An account can have only one valid auth_key and creating a new key will invalidate an existing key.

All public data in MG-RAST is available without an auth_key. All API queries for private data which either do not have an auth_key or use an invalid or expired auth_key will get a "insufficient permissions to view this data" response.

The auth_key can be included in the query string like:

http://api.metagenomics.anl.gov/1/annotation/sequence/mgm4447943.3?evalue=10&type=organism&source=SwissProt&auth=j6FNL61ekNarTgqupMma6eMx5

or in a request using curl like:

curl -X GET -H "auth: j6FNL61ekNarTgqupMma6eMx5" "http://api.metagenomics.anl.gov/1/annotation/sequence/mgm4447943.3?evalue=10&type=organism&source=SwissProt"

Note that for the curl command the quotes are necessary for the query to be passed to the API correctly.

If an optional parameter passed through the query string has a list of values only the first will be used. When multiple values are required, e.g. for multiple md5 checksum values, they can be passed to the API like:

curl -X POST -d '{"data":["000821a2e2f63df1a3873e4b280002a8","15bf1950bd9867099e72ea6516e3d602"]}' "http://api.metagenomics.anl.gov/m5nr/md5"

In some cases, the data requested is in the form of a list with a large number of entries. In these cases the limit and offset parameters can be used to step through the list, for example:

http://api.metagenomics.anl.gov/1/project?order=name&limit=20&offset=100

will limit the number of entries returned to 20 with an offset of 100. If these parameters are not provided default values of limit=10 and offset=0 are used. The returned JSON structure will contain the 'next' and 'prev' (previous) URIs to simplify stepping through the list.

The data returned may be plain text, compressed gzipped files or a JSON structure.

Most API queries are 'synchronous' and results are returned immediately. Some queries may require a substantial time to compute results, in these cases you can select the asynchronous option by adding '&asynchronous=1' to the end of the query string. This query will then return a URL which will return the query results when they are ready.


annotation

Description

All annotations of a metagenome for a specific annotation type and source

info - request

Description

Returns description of parameters and attributes.

This is a synchronous GET request. This request has no parameters.

sequence - request

Description

tab deliminted annotated sequence stream

This is a stream GET request.

Parameters

Example

Return Attributes

similarity - request

Description

tab deliminted blast m8 with annotation

This is a stream GET request.

Parameters

Example

Return Attributes


compute

Description

Calculate various statistics for given input data.

info - request

Description

Returns description of parameters and attributes.

This is a synchronous GET request. This request has no parameters.

alphadiversity - request

Description

Calculate alpha diversity value for given ID and taxon level.

This is a synchronous GET request.

Parameters

Example

Return Attributes

normalize - request

Description

Calculate normalized values for given input data.

This is a synchronous POST request.

Parameters

Example

Return Attributes

significance - request

Description

Calculate significance values for given input data.

This is a synchronous POST request.

Parameters

Example

Return Attributes

heatmap - request

Description

Calculate a dendogram for given input data.

This is a synchronous POST request.

Parameters

Example

Return Attributes

pcoa - request

Description

Calculate a PCoA for given input data.

This is a synchronous POST request.

Parameters

Example

Return Attributes


download

Description

An analysis file from the processing of a metagenome from a specific stage in its analysis

info - request

Description

Returns description of parameters and attributes.

This is a synchronous GET request. This request has no parameters.

instance - request

Description

Returns a single sequence file.

This is a synchronous GET request.

Parameters

Example

Return Attributes

setlist - request

Description

Returns a list of sets of sequence files for the given id.

This is a synchronous GET request.

Parameters

Example

Return Attributes


inbox

Description

inbox receives user inbox data upload, requires authentication, see http://blog.metagenomics.anl.gov/mg-rast-v3-2-faq/#api_submission for details

info - request

Description

Returns description of parameters and attributes.

This is a synchronous GET request. This request has no parameters.

view - request

Description

lists the contents of the user inbox

This is a synchronous GET request.

Parameters

Example

Return Attributes

upload - request

Description

receives user inbox data upload

This is a synchronous POST request.

Parameters

Example

Return Attributes


library

Description

A library of metagenomic samples from some environment

info - request

Description

Returns description of parameters and attributes.

This is a synchronous GET request. This request has no parameters.

query - request

Description

Returns a set of data matching the query criteria.

This is a synchronous GET request.

Parameters

Example

Return Attributes

instance - request

Description

Returns a single data object.

This is a synchronous GET request.

Parameters

Example

Return Attributes


m5nr

Description

M5NR provides data through a comprehensive non-redundant protein / rRNA database

info - request

Description

Returns description of parameters and attributes.

This is a synchronous GET request. This request has no parameters.

ontology - request

Description

Return functional hierarchy

This is a synchronous GET request.

Parameters

Example

Return Attributes

taxonomy - request

Description

Return organism hierarchy

This is a synchronous GET request.

Parameters

Example

Return Attributes

sources - request

Description

Return all sources in M5NR

This is a synchronous GET request.

Parameters

Example

Return Attributes

accession - request

Description

Return annotation of given source protein ID

This is a synchronous GET request.

Parameters

Example

Return Attributes

alias - request

Description

Return annotations for alias IDs containing the given text

This is a synchronous GET request.

Parameters

Example

Return Attributes

md5 - request

Description

Return annotation(s) or sequence of given md5sum (M5NR ID)

This is a synchronous GET request.

Parameters

Example

Return Attributes

function - request

Description

Return annotations for function names containing the given text

This is a synchronous GET request.

Parameters

Example

Return Attributes

organism - request

Description

Return annotations for organism names containing the given text

This is a synchronous GET request.

Parameters

Example

Return Attributes

sequence - request

Description

Return annotation(s) for md5sum (M5NR ID) of given sequence

This is a synchronous GET request.

Parameters

Example

Return Attributes

accession - request

Description

Return annotations of given source protein IDs

This is a synchronous POST request.

Parameters

Example

Return Attributes

alias - request

Description

Return annotations for aliases containing the given texts

This is a synchronous POST request.

Parameters

Example

Return Attributes

md5 - request

Description

Return annotations or sequences of given md5sums (M5NR ID)

This is a synchronous POST request.

Parameters

Example

Return Attributes

function - request

Description

Return annotations for function names containing the given texts

This is a synchronous POST request.

Parameters

Example

Return Attributes

organism - request

Description

Return annotations for organism names containing the given texts

This is a synchronous POST request.

Parameters

Example

Return Attributes

sequence - request

Description

Return annotations for md5s (M5NR ID) of given sequences

This is a synchronous POST request.

Parameters

Example

Return Attributes


matrix

Description

A profile in biom format that contains abundance counts

info - request

Description

Returns description of parameters and attributes.

This is a synchronous GET request. This request has no parameters.

organism - request

Description

Returns a BIOM object.

This is a synchronous or asynchronous GET request.

Parameters

Example

Return Attributes

function - request

Description

Returns a BIOM object.

This is a synchronous or asynchronous GET request.

Parameters

Example

Return Attributes

feature - request

Description

Returns a BIOM object.

This is a synchronous or asynchronous GET request.

Parameters

Example

Return Attributes


metadata

Description

Metagenomic metadata is data providing information about one or more aspects of a set sequences from a sample of some environment

info - request

Description

Returns description of parameters and attributes.

This is a synchronous GET request. This request has no parameters.

template - request

Description

Returns static template for metadata object relationships and types

This is a synchronous GET request.

Parameters

Example

Return Attributes

cv - request

Description

Returns static controlled vocabularies used in metadata. By default returns all CVs at latest version. If label and version options used, returns those specific values.

This is a synchronous GET request.

Parameters

Example

Return Attributes

ontology - request

Description

Returns static ontology used in metadata for the given name and version.

This is a synchronous GET request.

Parameters

Example

Return Attributes

export - request

Description

Returns full nested metadata for a project in same format as template, or metadata for a single metagenome.

This is a synchronous GET request.

Parameters

Example

Return Attributes

import - request

Description

Create project with given metadata spreadsheet and metagenome IDs, either upload or shock node

This is a synchronous POST request.

Parameters

Example

Return Attributes

update - request

Description

Update project with given metadata spreadsheet and metagenome IDs, either upload or shock node

This is a synchronous POST request.

Parameters

Example

Return Attributes

validate - request

Description

Validate given metadata spreadsheet, either upload or shock node

This is a synchronous POST request.

Parameters

Example

Return Attributes

validate - request

Description

Validate given metadata value

This is a synchronous GET request.

Parameters

Example

Return Attributes


metagenome

Description

A metagenome is an analyzed set sequences from a sample of some environment

info - request

Description

Returns description of parameters and attributes.

This is a synchronous GET request. This request has no parameters.

query - request

Description

Returns a set of data matching the query criteria.

This is a synchronous GET request.

Parameters

Example

Return Attributes

instance - request

Description

Returns a single data object.

This is a synchronous GET request.

Parameters

Example

Return Attributes


profile

Description

A profile in biom format that contains abundance and similarity values

info - request

Description

Returns description of parameters and attributes.

This is a synchronous GET request. This request has no parameters.

instance - request

Description

Returns a single data object in BIOM format

This is a synchronous GET request.

Parameters

Return Attributes


project

Description

A project is a composition of samples, libraries and metagenomes being analyzed in a global context.

info - request

Description

Returns description of parameters and attributes.

This is a synchronous GET request. This request has no parameters.

query - request

Description

Returns a set of data matching the query criteria.

This is a synchronous GET request.

Parameters

Example

Return Attributes

instance - request

Description

Returns a single data object.

This is a synchronous GET request.

Parameters

Example

Return Attributes


sample

Description

A metagenomic sample from some environment.

info - request

Description

Returns description of parameters and attributes.

This is a synchronous GET request. This request has no parameters.

query - request

Description

Returns a set of data matching the query criteria.

This is a synchronous GET request.

Parameters

Example

Return Attributes

instance - request

Description

Returns a single data object.

This is a synchronous GET request.

Parameters

Example

Return Attributes


server

Description

The server resource returns information about a server.

info - request

Description

Returns the server information.

This is a synchronous GET request. This request has no parameters.

instance - request

Description

Returns a single user object.

This is a synchronous GET request.

Parameters

Example

Return Attributes


validation

Description

validates templates for correct structure and data to fit a valid template

info - request

Description

Returns description of parameters and attributes.

This is a synchronous GET request. This request has no parameters.

template - request

Description

Checks if the referenced JSON structure is a valid template

This is a synchronous GET request.

Parameters

Example

Return Attributes

data - request

Description

Returns a single data object.

This is a synchronous GET request.

Parameters

Example

Return Attributes