# Ensembl External References UniProt: Step-by-Step Guide By the end of this guide you will be able to take any Ensembl gene, transcript, or peptide identifier, find the UniProt entries linked to it, export a genome-wide gene-to-UniProt table, and verify a mapping before you build an analysis on it. The walkthrough covers four access routes: the [Ensembl genome browser](/blog/guides/ensembl-genome-browser), the Ensembl REST API, BioMart with the biomaRt package, and the public Ensembl MySQL server. A closing section works the reverse direction, from a UniProt accession back to Ensembl, which is the situation a proteomics result usually creates. You need a web browser pointed at www.ensembl.org and www.uniprot.org, a terminal with curl installed, and, depending on which routes you adopt, the mysql command-line client, R 4.x with the biomaRt package from Bioconductor, and Python 3. Every command runs in a standard Linux or macOS shell and in Windows terminals where curl is available. Ensembl is an open platform integrating publicly available genomics data across the tree of life, focused on eukaryotic species related to human health, agriculture, and biodiversity, and it now represents more than 4,800 eukaryotic and more than 31,300 prokaryotic genomes [1]. UniProt is the reference protein knowledgebase that Ensembl links to through its external reference system, usually shortened to xref. If you are new to the resource, the browser steps below double as a compact Ensembl [genome browser tutorial](/blog/guides/genome-browsers-for-researchers-a-guide-to-inspecting-genomic-evidence) for the pages this workflow depends on. ## What External References Mean in Ensembl, and Where UniProt Fits An external reference is a stored link between an Ensembl object, such as a gene, a transcript, or a peptide, and an entry in another database. Ensembl maintains connections to dozens of external databases, from HGNC and NCBI Gene to PDB and GO, and gene pages group them all under the External references section. UniProt produces UniProtKB in two sections. Swiss-Prot entries are reviewed and manually annotated by UniProt curators. TrEMBL entries are unreviewed and annotated computationally. Ensembl stores the two sections as separate external databases with the exact names UniProt/SWISSPROT and UniProt/TrEMBL, and that spelling matters whenever you filter, because a near miss returns an empty result rather than an error. Links attach at different levels of the Ensembl model. HGNC and NCBI Gene references hang off genes. UniProt references hang off peptides, the translation objects Ensembl numbers with ENSP identifiers. The gene page aggregates xrefs across its whole gene model, which is why the web page shows UniProt entries even though a gene-level API call does not. Some xrefs are direct, created by comparing Ensembl sequences against the external entry. Others are dependent, meaning Ensembl reached the external entry through an intermediate database. Both appear on the page and both are usable, and the distinction explains why two apparently equivalent links can carry different types. These links carry real weight in downstream resources. CancerGenes, built to simplify gene selection for cancer genome projects, annotates each gene with functional description, protein length, transcript count, and links to Entrez Gene, COSMIC, and the UCSC and Ensembl genome browsers [2]. GeneCaRNA assembles its genome-mapped non-coding RNA gene set by integrating entries from RNAcentral, HGNC, Ensembl, and NCBI Gene, producing 219,587 ncRNA gene pages [3]. A resource that resolves an identifier is consuming exactly the cross-reference layer this guide works with. One more piece of context saves hours of confusion later. Ensembl issues new releases several times a year, and the release number is embedded in dataset and database names. That number, together with the genome assembly, is the single most useful piece of metadata to record with any export. ## How to Use Ensembl: Four Access Routes to UniProt Cross-References ![Decision tree guiding readers to the browser, REST API, BioMart, MySQL or UniProt ID mapping based on how many identifiers they have.](/article-images/illustrations/ensembl-external-references-uniprot-route-choice.webp) Pick the route by scale and by how much control you need. | Route | Best for | Practical scale | Key parameter or command | |--|--|--|--| | Genome browser pages | One gene, visual check | 1 to 10 genes | Search box, External references section | | REST API | Scripts and live lookups | 1 to 1,000 IDs per POST | GET /xrefs/id/{id}?external=UniProt/SWISSPROT | | BioMart or biomaRt | Bulk attribute export | Thousands of genes | attributes uniprotswissprot, uniprotsptrembl | | Public MySQL server | Full-database joins | Millions of rows | ensembldb.ensembl.org, port 5306 | | UniProt ID mapping | Reverse direction, accession to Ensembl | Thousands | www.uniprot.org/id-mapping | Two rules of thumb keep the choice simple. Use the browser to understand what a mapping is, REST to automate it, and BioMart to export it. Move to MySQL when you need joins BioMart cannot express, and start from the UniProt ID mapping service when your input is already a list of accessions. ## Step-by-Step: Ensembl External References UniProt Workflow The steps use BRCA2 and TP53 as running examples, with the well-characterized UniProt entries P51587 and P04637. Identifiers, version suffixes, and coordinates shift between releases, so treat every output block as representative and re-run the commands against the current release. ### Step 1. Locate the gene in the Ensembl genome browser 1. Open www.ensembl.org and type BRCA2 human in the search box. Choose the Gene result, not the Transcript or Protein result. 2. Read the page header. It names the species, the assembly (GRCh38 for human), and the Ensembl release number. Write both down, because no export is reproducible without them. 3. Scroll to the External references section of the gene page, or open External references in the left menu on the classic site. Entries are grouped by database, and under UniProt/SWISSPROT you should find P51587 for BRCA2. 4. Click through to the peptide page for the protein-level view, which draws UniProt features alongside other protein annotations. The new Ensembl site, currently in beta, provides genome, gene, transcript, homology, and variation views and already holds more than 2,700 eukaryotic genome assemblies, and it is intended to replace the older interface, so expect small navigation differences between the two [1]. The underlying release is the same. ### Step 2. Retrieve UniProt cross-references with the REST API ![Diagram showing a gene lookup pulled open to transcripts and peptides, then xrefs calls giving Swiss-Prot or TrEMBL accessions.](/article-images/illustrations/ensembl-external-references-uniprot-gene-to-accession.webp) The REST server at rest.ensembl.org returns JSON over plain HTTPS, needs no account, and allows 15 requests per second per IP address. Start by expanding the gene into its transcripts and translations. ```bash curl -s -H "Content-Type: application/json" \ "https://rest.ensembl.org/lookup/id/ENSG00000139618?expand=1" ``` The -s flag suppresses the progress meter. The Content-Type header negotiates JSON output. The expand=1 parameter pulls the full transcript list with translation objects inline. Abbreviated output: ```json { "assembly_name": "GRCh38", "biotype": "protein_coding", "canonical_transcript": "ENST00000381192", "chr": "13", "description": "BRCA2 DNA repair associated", "display_id": "BRCA2", "end": 32973805, "id": "ENSG00000139618", "species": "homo_sapiens", "start": 32315480, "strand": -1, "transcripts": ["one object per transcript, coding transcripts carry a translation object"] } ``` The coordinates belong to GRCh38 and move between assemblies. Two fields deserve attention. biotype tells you whether the gene is protein_coding, which predicts whether translations exist at all, and canonical_transcript names the transcript Ensembl treats as canonical, which is useful when you want exactly one peptide per gene. The transcripts array is where peptide identifiers live. Take the translation id from each coding transcript and query xrefs at the peptide level: ```bash curl -s -H "Content-Type: application/json" \ "https://rest.ensembl.org/xrefs/id/ENSP00000269305?external=UniProt/SWISSPROT" ``` ```json [ { "primary_id": "P04637", "display_id": "P04637", "dbname": "UniProt/SWISSPROT" } ] ``` The external parameter filters by database name and takes the exact Ensembl names, UniProt/SWISSPROT and UniProt/TrEMBL among them. Remove the filter and the same call returns every linked database, from PDB to GO, often dozens of entries for one peptide. The primary_id field is the value you export. When you start from a symbol instead of a stable identifier, use the symbol route: ```bash curl -s -H "Content-Type: application/json" \ "https://rest.ensembl.org/xrefs/symbol/human/TP53?external=UniProt/SWISSPROT" ``` ```json [ { "id": "ENSG00000141510", "display_id": "TP53", "type": "gene" } ] ``` The first path segment is the species, human here. Symbol lookups can return several matches when a symbol is shared between loci, so check the type field before you proceed. ### Step 3. Batch many identifiers in one POST Single GET calls exhaust the rate limit quickly on real workloads. The batch endpoints accept up to 1,000 identifiers per request: ```bash curl -s -X POST \ -H "Content-Type: application/json" \ -d '{"ids": ["ENSP00000269305", "ENSP00000381192"], "external": "UniProt/SWISSPROT"}' \ "https://rest.ensembl.org/xrefs/id?content-type=application/json" ``` Representative output, one block per input identifier: ```json { "ENSP00000269305": [ { "primary_id": "P04637", "dbname": "UniProt/SWISSPROT" } ], "ENSP00000381192": [ { "primary_id": "P51587", "dbname": "UniProt/SWISSPROT" } ] } ``` Check that every input identifier appears in the response. A missing key usually means the identifier was unknown in the current release, which the single-identifier call reports as a JSON error object naming the unknown ID. Parse defensively, because container shapes differ between endpoints. ### Step 4. Export bulk mappings with BioMart and biomaRt For a few hundred to a few million rows, BioMart is the fastest point-and-click route: 1. Open www.ensembl.org/biomart, or follow the BioMart link in the header of any Ensembl page. 2. Choose the Ensembl Genes database, then the Homo sapiens genes dataset. The dataset label carries the release number, which doubles as your reproducibility record. 3. Open FILTERS. Paste gene, transcript, or peptide identifiers into the identifier filter, restrict by chromosome, or set Gene type to protein_coding to shrink coding-only exports. Leave filters empty for everything. 4. Open ATTRIBUTES. Under GENE keep Ensembl Gene ID, Ensembl Transcript ID, and Ensembl Protein ID. Under EXTERNAL select UniProt/Swiss-Prot ID and UniProt/TrEMBL ID. 5. Click RESULTS, then Export all rows to File in TSV format. The same export in R looks like this: ```r library(biomaRt) ensembl <- useEnsembl(biomart = "genes", dataset = "hsapiens_gene_ensembl") results <- getBM( attributes = c("ensembl_gene_id", "ensembl_transcript_id", "ensembl_peptide_id", "uniprotswissprot", "uniprotsptrembl"), filters = "ensembl_gene_id", values = c("ENSG00000139618", "ENSG00000141510"), mart = ensembl ) head(results) ``` Expected shape of the result, one row per transcript: ``` ensembl_gene_id ensembl_transcript_id ensembl_peptide_id uniprotswissprot uniprotsptrembl 1 ENSG00000139618 ENST00000381192 ENSP00000381192 P51587 2 ENSG00000141510 ENST00000269305 ENSP00000269305 P04637 ``` Four parameters matter here. attributes names the output columns, filters names the input key, values carries the identifiers, and mart points at the dataset object. Attribute names are case sensitive, and uniprotswissprot and uniprotsptrembl are the two UniProt columns. Run searchAttributes(ensembl, pattern = "uniprot") to list every UniProt-related attribute, including gene name and isoform options, and copy the exact strings from that output. If the main host is slow, useEnsembl accepts mirror = "useast". A genome-wide human export with these attributes produces several hundred thousand rows, one per coding transcript, so plan the downstream storage and deduplicate per gene or per peptide depending on the question. ### Step 5. Query the public Ensembl MySQL server Ensembl exposes its core databases on a public MySQL server. Connect read-only as anonymous: ```bash mysql -u anonymous -h ensembldb.ensembl.org -P 5306 \ -D homo_sapiens_core_113_38 ``` The -u flag names the user, anonymous, which needs no password. The -h flag sets the host, capital -P sets the port to 5306, and lowercase -p would prompt for a password, so leave it out. The -D flag selects the database. Database names follow the pattern species_core_release_assembly, so replace 113 with the current release number shown on the Ensembl home page. Four tables drive the mapping. xref holds one row per external entry, with the accession in display_label. external_db is the registry that maps numeric external_db_id values to names like UniProt/SWISSPROT. object_xref links an xref to an Ensembl object through ensembl_id and ensembl_object_type. translation holds peptides with stable_id values like ENSP00000269305. ```bash mysql -u anonymous -h ensembldb.ensembl.org -P 5306 \ -D homo_sapiens_core_113_38 \ -e "SELECT x.display_label AS uniprot_accession, d.db_name AS source_db FROM object_xref ox JOIN xref x ON x.xref_id = ox.xref_id JOIN external_db d ON d.external_db_id = x.external_db_id JOIN translation t ON t.translation_id = ox.ensembl_id WHERE ox.ensembl_object_type = 'Translation' AND d.db_name LIKE 'UniProt%' AND t.stable_id = 'ENSP00000269305'" ``` The -e flag runs the query and prints the result without opening an interactive session. Expected output: ``` +-------------------+-------------------+ | uniprot_accession | source_db | +-------------------+-------------------+ | P04637 | UniProt/SWISSPROT | +-------------------+-------------------+ ``` To check the result, drop the stable_id condition, add t.stable_id to the SELECT list, and run a GROUP BY on d.db_name. You should see exactly two groups, UniProt/SWISSPROT and UniProt/TrEMBL, and their combined row count should match a BioMart export from the same release. For a genome-wide table, remove the stable_id condition and redirect the output to a file, for example appending > uniprot_map.tsv to the command. ### Step 6. Cross-check the mapping on the UniProt side Open www.uniprot.org, search P51587, and scroll to the Cross-references section. The Ensembl block lists the linked transcript and protein identifiers, and for BRCA2 you should see the canonical ENST and ENSP pair. If an accession you exported from Ensembl does not appear there, check the release dates on both sides before you conclude the link is wrong, because the two resources update on different schedules. For lists, the UniProt ID mapping service at www.uniprot.org/id-mapping converts UniProt accessions to Ensembl gene, transcript, and protein identifiers. This is the reverse direction of everything above, and it is the fastest route when a mass spectrometry result hands you a column of accessions. Treat the two directions as independent pipelines. UniProt curates its own cross-references and Ensembl computes its own, so they agree in the great majority of cases but are not guaranteed to be identical at any given moment. Spot-check a small sample whenever the mapping drives a decision. ## Worked Example: Build a Gene-to-UniProt Table for a Candidate List The script below turns a list of gene identifiers into a tab-separated gene, peptide, UniProt table using only the Python standard library. The 0.1 second pause keeps the request rate under the 15 per second ceiling. ```python import json import time import urllib.request BASE = "https://rest.ensembl.org" GENES = ["ENSG00000139618", "ENSG00000141510"] def get_json(path): request = urllib.request.Request(BASE + path, headers={"Content-Type": "application/json"}) with urllib.request.urlopen(request) as response: return json.loads(response.read()) for gene_id in GENES: gene = get_json(f"/lookup/id/{gene_id}?expand=1") for tx in gene.get("transcripts", []): translation = tx.get("translation") if not translation: continue ensp = translation["id"] xrefs = get_json(f"/xrefs/id/{ensp}?external=UniProt/SWISSPROT") accessions = ",".join(x["primary_id"] for x in xrefs) or "NA" print(f"{gene['display_id']}\t{ensp}\t{accessions}") time.sleep(0.1) ``` Expected output for the two example genes: ``` BRCA2 ENSP00000381192 P51587 TP53 ENSP00000269305 P04637 ``` NA marks a coding peptide with no Swiss-Prot match, which is normal for short or lowly supported isoforms. For real runs, read GENES from a file, write rows with a csv writer, and record the release number in the output header. Sensible next steps once the table exists are proteomics annotation against the exported accessions, variant annotation with the Ensembl Variant Effect Predictor, a tool Ensembl continues to expand [1], and archiving the raw JSON next to the final table so the mapping can be audited later. ## How the Ensembl UniProt Mapping Behaves Expect many-to-many. Ensembl builds one peptide per coding transcript, and UniProt has one entry per protein plus separate isoform entries written with a dash and a number, such as P51587-2. A gene with twelve transcripts can produce a dozen peptide-to-accession links, and one accession can match peptides from more than one transcript. Deduplicate deliberately, per gene or per peptide, and never assume a one-to-one join. Choose the section before you publish. Swiss-Prot links give you curated entries with stable accessions, which suits annotation tables. TrEMBL links cover proteins the reviewed section does not, which suits completeness. Keeping the two in separate columns, as the BioMart attributes do, preserves that choice for whoever uses the table next. Release churn is real. Ensembl recomputes xrefs as its own annotation, UniProt content, and the underlying assembly evolve, so counts move between releases even for stable genes. Record the release number, the assembly, and the exact database names with every export, and re-run the mapping when you upgrade. Empty results are informative, not broken. Novel peptides, short isoforms, and pseudogene fragments often have no UniProt match. Remember also that dependent xrefs, reached through an intermediate database, sit alongside direct ones, and the gene page groups them so you can see which is which before you cite a link. ## Tips for Reliable UniProt Cross-References - Filter at the source. The external parameter on REST calls and the EXTERNAL attribute group in BioMart return only the columns you need, which keeps files small and joins clean. - Use expand=1 on lookup calls to fetch the whole gene model, including every ENSP, in one request instead of one per transcript. - Batch with POST. Up to 1,000 identifiers per request keeps you far away from the 15 requests per second ceiling. - Anchor on canonical transcripts when you need one row per gene. The lookup response names the canonical transcript, so join on that field. - Discover names with searchAttributes and searchFilters in biomaRt instead of guessing attribute spellings. - Record metadata in the output itself. A header line with release, assembly, database names, and retrieval date turns a mystery file into a citable result. - Spot-check before you commit. Take ten random rows, open the accessions on www.uniprot.org, and confirm the Ensembl lines agree with your export. - Use the official training. Ensembl maintains help pages, documentation, and an extensive training program accessible through its training pages, which cover the browser, BioMart, and REST in depth [1]. - Archive raw outputs. Keep the JSON or TSV you downloaded, with the retrieval date, so a release change never silently rewrites your results. ## Common Mistakes and Limitations - Querying a gene ID for UniProt xrefs and getting an empty list. UniProt references attach to peptides, so a gene-level xrefs call returns nothing for them. Expand the gene first and call xrefs on each ENSP, or let BioMart do the join. - Assuming one gene equals one UniProt entry. Multi-transcript genes routinely map to several entries, and shared domains can map one entry to several peptides. Count rows before you summarize. - Misspelling the database name in the external filter. The names are UniProt/SWISSPROT and UniProt/TrEMBL. Variants like UniProtKB or Swiss-Prot alone return an empty array rather than an error, which looks like the gene has no links. - Guessing biomaRt attribute names. A wrong name makes getBM stop with an attribute error or return empty columns. Run searchAttributes(ensembl, pattern = "uniprot") and copy the exact strings. - Tripping the rate limit. Exceeding 15 requests per second on rest.ensembl.org returns HTTP 429 Too Many Requests. Add a delay, batch with POST, or spread the work over time. - Supplying a password to the MySQL server. Adding -p produces ERROR 1045 (28000): Access denied for user 'anonymous'. The anonymous account needs no password, so omit -p. Connection failures showing ERROR 2003 usually mean a firewall is blocking port 5306. - Mixing versioned and unversioned identifiers. Ensembl IDs carry version suffixes that increment between releases, so the same transcript can carry a different suffix in your next export. Strip versions for joins, or keep them everywhere, but never mix the two within one column. - Ignoring the assembly. The main site serves GRCh38, while GRCh37 lives on the archive at grch37.ensembl.org. Coordinates and sometimes identifiers differ between them, so never combine exports across assemblies. - Expecting UniProt accessions inside Ensembl GTF files. GTF carries gene, transcript, and exon features with gene_id and transcript_id attributes, not external accessions. Use GTF for structure and the routes in this guide for cross-references. - Treating an xref as sequence proof. Cross-references are pipeline products. When a mapping matters, download the peptide FASTA from the Ensembl FTP site and compare it against the UniProt sequence, or run the peptide through the BLAST tool on www.uniprot.org. - Confusing the two site interfaces. The new Ensembl site is in beta and will replace the older one, and menu labels differ between them [1]. The External references content is the same either way. Cross-references reflect annotation pipelines, not experimental validation, and they change with every release, so treat them as a current best map rather than a permanent truth. Project-level conclusions still need expert review of the underlying entries. ## Frequently Asked Questions ### What is the difference between UniProt/SWISSPROT and UniProt/TrEMBL in Ensembl external references? UniProt/SWISSPROT links point to reviewed entries that UniProt curators annotate manually, while UniProt/TrEMBL links point to unreviewed entries annotated computationally. Ensembl stores them as two separate external databases, so filter each one deliberately. ### Why does one Ensembl gene map to several UniProt entries? Ensembl builds one peptide per coding transcript and UniProt has one entry per protein plus isoforms, so a multi-transcript gene can match several entries. The mapping is many-to-many by design. ### Which Ensembl identifier should I use for UniProt mapping, gene, transcript, or peptide? Use the peptide identifier, ENSP, when you call the REST xrefs endpoint directly, because UniProt references attach to translations. The gene page and BioMart resolve the gene-to-peptide step for you. ### Do Ensembl external references change between releases? Yes. Xrefs are recomputed as Ensembl, UniProt, and the assembly evolve, so record the release number and assembly with every export and re-run mappings after an upgrade. ### Can I download UniProt cross-references for every human gene at once? Yes. BioMart with the UniProt attributes, the biomaRt package, or a query against the public MySQL server returns genome-wide tables in minutes. ### Why does the Ensembl REST API return 429 Too Many Requests? You exceeded 15 requests per second, the documented limit for rest.ensembl.org. Add a short delay between calls or move to the batch POST endpoints, which accept up to 1,000 identifiers per request. ### How do I go from a UniProt accession back to an Ensembl gene? Open the UniProt entry and read the Ensembl lines in its Cross-references section, or submit the accessions to the UniProt ID mapping service at www.uniprot.org/id-mapping. ### Do Ensembl external references include databases other than UniProt? Yes. The same section and the same REST parameter cover HGNC, NCBI Gene, RefSeq, PDB, GO, and dozens of other databases. ## Sources 1. [Ensembl 2025](https://pubmed.ncbi.nlm.nih.gov/39656687/) 2. [CancerGenes: a gene selection resource for cancer genome projects](https://pubmed.ncbi.nlm.nih.gov/17088289/) 3. [GeneCaRNA: a comprehensive gene-centric database of human non-coding RNAs in the GeneCards Suite.](https://pubmed.ncbi.nlm.nih.gov/33676929/)