REST URLs for data retrieval

All data types and formats can be retrieved from the ENA browser using REST URLs.  These URLs are described here.

Retrieval using single identifiers

To retrieve results by a single identifier for all records other than Taxon and Project please, use the following URL syntax: http://www.ebi.ac.uk/ena/data/view/<identifier>

For example, the following URL returns the sequence entry with accession number A00145 in HTML format: http://www.ebi.ac.uk/ena/data/view/A00145.

For Taxon and Project records, respectively, please use the following URL syntax: http://www.ebi.ac.uk/ena/data/view/Taxon:<identifier> and http://www.ebi.ac.uk/ena/data/view/Project:<identifier>

For example, the following URL returns the Taxon record with identifier 9606: http://www.ebi.ac.uk/ena/data/view/Taxon:9606, and the following URL returns the Project record with identifier 20: http://www.ebi.ac.uk/ena/data/view/Project:20.

Note that in the case of projects, the "Project:" prefix need only be added if only the numerical project identifier is known. If the identifier begins with "PRJ", this is not needed. For example: http://www.ebi.ac.uk/ena/data/view/PRJEB2772

Retrieval using multiple identifiers

To retrieve results by ranges and lists of identifiers please use the following URL syntax:
http://www.ebi.ac.uk/ena/data/view/<identifier1>-<identifierN>
http://www.ebi.ac.uk/ena/data/view/<identifier1>,<identifier2>,<identifier3>,..<identifierN>

For example, the following URL returns all read domain experiments in the range ERA000010 to ERA000020 in HTML format: http://www.ebi.ac.uk/ena/data/view/ERA000010-ERA000020, and the following URL returns two taxons 4235 and 6543 in HTML format: http://www.ebi.ac.uk/ena/data/view/Taxon:4235,Taxon:6543.

Please note that accession number ranges cannot span different data classes.

Retrieval using organism names

Taxonomy retrieval (Taxon:) is supported using scientific names, common names and synonyms. Examples include:

Display options

The display parameter is used to specify the display format:

Option Description Example
display=html Results are displayed in HTML format. Supported by all ENA data classes. HTML is the default display format if no other display option has been specified. http://www.ebi.ac.uk/ena/data/view/ERA000092&display=html
display=xml Results are displayed in XML format. Supported by all ENA data classes. http://www.ebi.ac.uk/ena/data/view/A00145&display=xml
display=text Results are displayed in text format. Supported only by assembled and annotated sequence data classes. http://www.ebi.ac.uk/ena/data/view/A00145&display=text
display=fasta Results are displayed in fasta format. Supported by assembled and annotated sequence and Trace data classes. http://www.ebi.ac.uk/ena/data/view/A00145&display=fasta
display=fastq Results are displayed in fastq format. Supported only by Trace data class. http://www.ebi.ac.uk/ena/data/view/TI1941166100&display=fastq

Download options

The download parameter is used to specify that records are to be saved in a file:

Option Description
download=gzip Results are compressed using gzip and saved into a file.
download=txt Results are saved into a file without any compression.

Pagination options

Pagination is controlled by two URL parameters; the offset parameter defines the first record and the length parameter defines the number of records to retrieve. For example:
http://www.ebi.ac.uk/ena/data/view/CEQY01000001-CEQY01396425&display=fasta&download=gzip&offset=1&length=100000
http://www.ebi.ac.uk/ena/data/view/CEQY01000001-CEQY01396425&display=fasta&download=gzip&offset=100001&length=100000

Note that the use of pagination is more obvious for downloading search results than with the examples given above, as pagination of sequence ranges can be just as easily performed by changing the accession numbers in the range queries.

There is an additional limit parameter which is used to safe-guard the system and the user from unintentional download of millions of sequences. The limit sets the maximum number of records that can be downloaded and if not set will default to 100,000. To increase the maximum, set the limit to a larger number, for example:
http://www.ebi.ac.uk/ena/data/view/CEQY01000001-CEQY01396425&display=fasta&download=gzip&limit=400000

We advise that you increase the limit with caution.  Downloading very large numbers of very large sequences can result in more problems than downloading your set in batches, especially if you have a slower network connection. 

Examples

Retrieve read domain metadata in XML format

Read domain metadata XMLs can be retrieved using the display=xml parameter. For example, the URL http://www.ebi.ac.uk/ena/data/view/ERA000092&display=xml will return the submission object ERA000092 in XML format.

Retrieve assembled and annotated sequences in fasta format

Assembled and annotated sequences can be returned in fasta format using the display=fasta parameter. For example, the URL http://www.ebi.ac.uk/ena/data/view/A00145&display=fasta will return the sequence A00145 in fasta format.

Retrieve assembled and annotated subsequences in fasta format

The range parameter can be used in combination with the display=fasta option to return assembled and annotated subsequences in fasta format. For example, retrieval of a subsequence from sequence entry A00145 from bases 3 to 63 is done using the URL: http://www.ebi.ac.uk/ena/data/view/A00145&display=fasta&range=3-63.

Retrieve assembled and annotated subsequences in HTML format

The range parameter can be used in combination with the display=html [default] option to return assembled and annotated subsequences in HTML format. For example, retrieval of a subsequence from sequence entry A00145 from bases 3 to 63 is done using the URL: http://www.ebi.ac.uk/ena/data/view/A00145&range=3-63.

Retrieve assembled and annotated records in flat file format

Assembled and annotated records can be retrieved in flat file format using the display=text parameter. For example, the URL http://www.ebi.ac.uk/ena/data/view/A00145&display=text will return the sequence entry A00145 in flat file format.

Retrieve assembled and annotated sequence records in XML format

Assembled and annotated sequence records can be retrieved in XML format using the display=xml parameter. For example, the URL http://www.ebi.ac.uk/ena/data/view/A00145&display=xml will return the sequence entry A00145 in XML format.

Retrieve expanded CON records

To retrieve expanded CON records please use the expanded=true parameter. For example, the URL http://www.ebi.ac.uk/ena/data/view/AL513382&display=text&expanded=true will return the expanded CON entry AL513382 in flat file format.

Expanded CON records are different from CON records in two ways. Firstly, the expanded CON records contain the full sequence in addition to the contig assembly instructions. Secondly, if a CON record contains only source or gap features the expanded CON records will also display all features from the segment records.

Retrieve assembled and annotated sequence header in flat file format

To retrieve assembled and annotated sequence header in flat file format please use the header=true parameter, e.g.:

http://www.ebi.ac.uk/ena/data/view/BN000065&display=text&header=true

Retrieve assembled and annotated sequence header in XML format

To retrieve assembled and annotated sequence header in XML format please use the header=true parameter, e.g.:

http://www.ebi.ac.uk/ena/data/view/BN000065&display=xml&header=true

Retrieve assembled and annotated sequence records using sequence versions

Specific assembled and annotated sequence versions can be retrieved by appending the sequence version to the identifer: <identifier>.<sequence version>

In the html view (display=html), if the requested sequence version is below the current sequence version, a warning is shown with a link to historical sequence versions of the record, e.g.: http://www.ebi.ac.uk/ena/data/view/AM407889.1. Also, if the requested sequence version is higher than the current sequence version, a warning is shown: e.g.: http://www.ebi.ac.uk/ena/data/view/AM407889.12). Note that in html view links to historical versions of sequence records are always provided in the Navigation panel.

In the xml view (display=xml), the latest sequence version is always displayed, but an analogous warning can be constructed as both requested and returned sequence versions are presented: e.g.: http://www.ebi.ac.uk/ena/data/view/AM407889.1&display=xml.

In fasta and text view (display=fasta and display=text), the requested sequence version is returned directly, e.g.: http://www.ebi.ac.uk/ena/data/view/AM407889.1&display=fasta and http://www.ebi.ac.uk/ena/data/view/AM407889.1&display=text.

Retrieve assembled and annotated sequence graphical image

A graphical view is available for assembled and annotated sequence records that have feature/assembly annotation or a sequence. These views contain two components, feature/assembly and sequence, for which ranges to be viewed are defined separately using the featureRange and sequenceRange parameters.

For example, the URL http://www.ebi.ac.uk/ena/data/view/graphics/BN000065&featureRange=10-300000&sequenceRange=103-166 returns an image created from sequence entry BN000065 showing feature and assembly annotation from bases 10-300000 and sequence from bases 103-166.

Retrieve Taxon records in XML format

Taxon records can be retrieved in XML format using the display=xml parameter. For example, the URL http://www.ebi.ac.uk/ena/data/view/Taxon:2759&display=xml returns the taxonomy record for Eukaryota.

Retrieve Taxon records in Darwin Core XML format

Taxon records can be retrieved in Darwin Core XML format using the display=dwc parameter. For example, the URL http://www.ebi.ac.uk/ena/data/view/Taxon:2759&display=dwc returns the taxonomy record for Eukaryota in Darwin Core XML.

Retrieve Trace sequences in fasta format

Trace sequences can be returned in fasta format using the display=fasta parameter. For example, the URL http://www.ebi.ac.uk/ena/data/view/TI1&display=fasta will return the Trace sequence TI1 in fasta format.

Retrieve Trace sequences in fastq format

Trace sequences can be returned in fastq format using the display=fastq parameter. For example, the URL http://www.ebi.ac.uk/ena/data/view/TI1&display=fastq will return the Trace sequence TI1 in fastq format.

Retrieve Trace metadata in XML format

Trace metadata XMLs can be retrieved using the display=xml parameter. For example, the URL http://www.ebi.ac.uk/ena/data/view/TI1&display=xml will return the Trace T1 metadata in XML format.