051 API Reference E3c86ba6

ENA API Reference

Comprehensive reference for the European Nucleotide Archive REST APIs.

ENA Portal API

Base URL: https://www.ebi.ac.uk/ena/portal/api

Official Documentation: https://www.ebi.ac.uk/ena/portal/api/doc

Search Endpoint

Endpoint: /search

Method: GET

Description: Perform advanced searches across ENA data types with flexible filtering and formatting options.

Parameters:

Query Syntax:

ENA uses a specialized query language with operators:

• Equality: field_name="value" or field_name=value
• Wildcards: field_name="*partial*" (use * for wildcard)
• Range: field_name>=value AND field_name<=value
• Logical: query1 AND query2, query1 OR query2, NOT query
• Taxonomy: tax_eq(taxon_id) - exact match, tax_tree(taxon_id) - includes descendants
• Date ranges: collection_date>=2020-01-01 AND collection_date<=2023-12-31
• In operator: study_accession IN (PRJNA1,PRJNA2,PRJNA3)

Common Result Types:

• study - Research projects/studies
• sample - Biological samples
• read_run - Raw sequencing runs
• read_experiment - Sequencing experiment metadata
• analysis - Analysis results
• assembly - Genome/transcriptome assemblies
• sequence - Assembled sequences
• taxon - Taxonomic records
• coding - Protein coding sequences
• noncoding - Non-coding sequences

Example Requests:

import requests

# Search for human samples
url = "https://www.ebi.ac.uk/ena/portal/api/search"
params = {
    "result": "sample",
    "query": "tax_eq(9606)",
    "format": "json",
    "fields": "accession,sample_title,collection_date",
    "limit": 100
}
response = requests.get(url, params=params)

# Search for RNA-seq experiments in a study
params = {
    "result": "read_experiment",
    "query": 'study_accession="PRJNA123456" AND library_strategy="RNA-Seq"',
    "format": "tsv"
}
response = requests.get(url, params=params)

# Find assemblies for E. coli with minimum contig N50
params = {
    "result": "assembly",
    "query": "tax_tree(562) AND contig_n50>=50000",
    "format": "json"
}
response = requests.get(url, params=params)

Fields Endpoint

Endpoint: /returnFields

Method: GET

Description: List available fields for a specific result type.

Parameters:

Example:

# Get all available fields for samples
url = "https://www.ebi.ac.uk/ena/portal/api/returnFields"
params = {"result": "sample"}
response = requests.get(url, params=params)
fields = response.json()

Results Endpoint

Endpoint: /results

Method: GET

Description: List available result types.

Example:

url = "https://www.ebi.ac.uk/ena/portal/api/results"
response = requests.get(url)

File Report Endpoint

Endpoint: /filereport

Method: GET

Description: Get file information and download URLs for reads and analyses.

Parameters:

Common File Report Fields:

• run_accession - Run accession number
• fastq_ftp - FTP URLs for FASTQ files (semicolon-separated)
• fastq_aspera - Aspera URLs for FASTQ files
• fastq_md5 - MD5 checksums (semicolon-separated)
• fastq_bytes - File sizes in bytes (semicolon-separated)
• submitted_ftp - FTP URLs for originally submitted files
• sra_ftp - FTP URL for SRA format file

Example:

# Get FASTQ download URLs for a run
url = "https://www.ebi.ac.uk/ena/portal/api/filereport"
params = {
    "accession": "ERR123456",
    "result": "read_run",
    "format": "json",
    "fields": "run_accession,fastq_ftp,fastq_md5,fastq_bytes"
}
response = requests.get(url, params=params)
file_info = response.json()

# Download FASTQ files
for ftp_url in file_info[0]['fastq_ftp'].split(';'):
    # Download from ftp://ftp.sra.ebi.ac.uk/...
    pass

ENA Browser API

Base URL: https://www.ebi.ac.uk/ena/browser/api

Official Documentation: https://www.ebi.ac.uk/ena/browser/api/doc

XML Retrieval

Endpoint: /xml/{accession}

Method: GET

Description: Retrieve record metadata in XML format.

Parameters:

Example:

# Get sample metadata in XML
accession = "SAMEA123456"
url = f"https://www.ebi.ac.uk/ena/browser/api/xml/{accession}"
response = requests.get(url)
xml_data = response.text

# Get study with cross-references
url = f"https://www.ebi.ac.uk/ena/browser/api/xml/PRJNA123456"
params = {"includeLinks": "true"}
response = requests.get(url, params=params)

Text Retrieval

Endpoint: /text/{accession}

Method: GET

Description: Retrieve sequences in EMBL flat file format.

Parameters:

Example:

# Get sequence in EMBL format
url = "https://www.ebi.ac.uk/ena/browser/api/text/LN847353"
response = requests.get(url)
embl_format = response.text

FASTA Retrieval

Endpoint: /fasta/{accession}

Method: GET

Description: Retrieve sequences in FASTA format.

Parameters:

Example:

# Get full sequence
url = "https://www.ebi.ac.uk/ena/browser/api/fasta/LN847353"
response = requests.get(url)
fasta_data = response.text

# Get subsequence
url = "https://www.ebi.ac.uk/ena/browser/api/fasta/LN847353"
params = {"range": "1000-2000"}
response = requests.get(url, params=params)

Links Retrieval

Endpoint: /links/{source}/{accession}

Method: GET

Description: Get cross-references to external databases.

Parameters:

Example:

# Get all links for a sample
url = "https://www.ebi.ac.uk/ena/browser/api/links/sample/SAMEA123456"
response = requests.get(url)

ENA Taxonomy REST API

Base URL: https://www.ebi.ac.uk/ena/taxonomy/rest

Description: Query taxonomic information including lineage and rank.

Tax ID Lookup

Endpoint: /tax-id/{taxon_id}

Method: GET

Description: Get taxonomic information by NCBI taxonomy ID.

Example:

# Get E. coli taxonomy
taxon_id = "562"
url = f"https://www.ebi.ac.uk/ena/taxonomy/rest/tax-id/{taxon_id}"
response = requests.get(url)
taxonomy = response.json()
# Returns: taxId, scientificName, commonName, rank, lineage, etc.

Scientific Name Lookup

Endpoint: /scientific-name/{name}

Method: GET

Description: Search by scientific name (may return multiple matches).

Example:

# Search by scientific name
name = "Escherichia coli"
url = f"https://www.ebi.ac.uk/ena/taxonomy/rest/scientific-name/{name}"
response = requests.get(url)

Suggest Names

Endpoint: /suggest-for-submission/{partial_name}

Method: GET

Description: Get taxonomy suggestions for submission (autocomplete).

Example:

# Get suggestions
partial = "Escheri"
url = f"https://www.ebi.ac.uk/ena/taxonomy/rest/suggest-for-submission/{partial}"
response = requests.get(url)

Cross-Reference Service

Base URL: https://www.ebi.ac.uk/ena/xref/rest

Description: Access records related to ENA entries in external databases.

Get Cross-References

Endpoint: /json/{source}/{accession}

Method: GET

Description: Retrieve cross-references in JSON format.

Parameters:

Example:

# Get cross-references for an SRA accession
url = "https://www.ebi.ac.uk/ena/xref/rest/json/sra/SRR000001"
response = requests.get(url)
xrefs = response.json()

CRAM Reference Registry

Base URL: https://www.ebi.ac.uk/ena/cram

Description: Retrieve reference sequences used in CRAM files.

MD5 Lookup

Endpoint: /md5/{md5_checksum}

Method: GET

Description: Retrieve reference sequence by MD5 checksum.

Example:

# Get reference by MD5
md5 = "7c3f69f0c5f0f0de6d7c34e7c2e25f5c"
url = f"https://www.ebi.ac.uk/ena/cram/md5/{md5}"
response = requests.get(url)
reference_fasta = response.text

Rate Limiting and Error Handling

Rate Limits:

• Maximum: 50 requests per second
• Exceeding limit returns HTTP 429 (Too Many Requests)
• Implement exponential backoff when receiving 429 responses

Common HTTP Status Codes:

• 200 OK - Success
• 204 No Content - Success but no data returned
• 400 Bad Request - Invalid parameters
• 404 Not Found - Accession not found
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server error (retry with backoff)

Error Handling Pattern:

import time
import requests
from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry

def create_session_with_retries():
    """Create requests session with retry logic"""
    session = requests.Session()
    retries = Retry(
        total=5,
        backoff_factor=1,
        status_forcelist=[429, 500, 502, 503, 504],
        allowed_methods=["GET", "POST"]
    )
    adapter = HTTPAdapter(max_retries=retries)
    session.mount("https://", adapter)
    return session

# Usage
session = create_session_with_retries()
response = session.get(url, params=params)

Bulk Download Recommendations

For downloading large numbers of files or large datasets:

1. Use FTP directly instead of API for file downloads

   • Base FTP: ftp://ftp.sra.ebi.ac.uk/vol1/fastq/
   • Aspera for high-speed: era-fasp@fasp.sra.ebi.ac.uk:

2. Use enaBrowserTools command-line utility

   # Download by accession
   enaDataGet ERR123456
   
   # Download all runs from a study
   enaGroupGet PRJEB1234
   

3. Batch API requests with proper delays

   import time
   
   accessions = ["ERR001", "ERR002", "ERR003"]
   for acc in accessions:
       response = requests.get(f"{base_url}/xml/{acc}")
       # Process response
       time.sleep(0.02)  # 50 req/sec = 0.02s between requests
   

Query Optimization Tips

1. Use specific result types instead of broad searches
2. Limit fields to only what you need using fields parameter
3. Use pagination for large result sets (limit + offset)
4. Cache taxonomy lookups locally
5. Prefer JSON/TSV over XML when possible (smaller, faster)
6. Use includeAccessions/excludeAccessions to filter large result sets efficiently
7. Batch similar queries together when possible