# How to Link from UniProt to Human Protein Atlas: A Practical Guide By the end of this guide you will be able to take any list of human UniProt accessions, resolve each one to its [Human Protein Atlas](/blog/guides/human-protein-atlas) (HPA) gene page, and produce a merged table that carries UniProt annotations on one side and HPA tissue expression and pathology data on the other. The guide covers four methods in order of increasing scale: reading the cross-reference from a single UniProt entry, running the UniProt ID mapping tool, pulling the cross-references programmatically through the UniProt REST API, and joining HPA's own download files on the Ensembl gene identifier. What you need on hand: - A plain list of UniProt accessions (for example P04637, P04406, O15551), or gene names if that is all you have. - A computer with Python 3.9 or later, the `requests` and `pandas` packages installed (`pip install requests pandas`), and `curl` if you prefer the command line. - Internet access to `uniprot.org` and `proteinatlas.org`. No API key is required for either resource. If you are new to UniProt in general, this guide doubles as a short UniProt database tutorial, because every method here starts from the same entry structure and identifier system you will use anywhere else in UniProt. ## Why the UniProt and Human Protein Atlas Cross-Reference Matters UniProt and the Human [Protein Atlas](/blog/guides/protein-atlas) answer different questions about the same gene. UniProt tells you what the protein is, its sequence, domains, function, subcellular location, and the evidence behind each claim. HPA tells you where the gene is expressed across normal human tissues, cell types, and cancers, supported by antibody-based profiling and [transcriptomics](/knowledge/bioinformatics/modern-transcriptomics-bulk-single-cell-spatial). A uniprot human protein atlas cross-reference lets you move from a hit in a proteomics or screening dataset straight to spatial and tissue context, or in the reverse direction, from an HPA candidate to sequence-level annotation. The two resources do not share a primary identifier. UniProt entries are keyed by accessions such as P04637, while HPA pages are keyed by Ensembl gene identifiers such as ENSG00000141510. Gene names appear in both resources but are not stable keys, which is the root of most mapping mistakes covered later in this guide. There is also a deeper reason to build the link carefully rather than casually. A long-running analysis of human canonical protein counts (the number of distinct protein-coding loci, excluding most alternative splice isoforms) showed that nine major annotation portals, reviewed at the beginning of 2017, reported counts spread from 21,819 down to 18,891, and that the four-way cross-reference concordance within UniProt between Ensembl, Swiss-Prot, Entrez Gene, and HGNC dropped to 18,690 proteins [1]. That gap means even well-curated databases disagree on the edges of the protein-coding set. Notably, the same analysis points out that Swiss-Prot counts Human Protein Atlas antibody cross-references among its evidence criteria for protein existence, so the two resources are already wired together at the curation level [1]. Your job is to exploit that wiring correctly at the identifier level. ## Understand the Identifiers Before You Link Anything A cross-reference, in this context, is a pointer stored inside a database record that names a corresponding record in another database. UniProt stores such pointers for dozens of external resources, and HPA is one of them. Four identifiers matter for this workflow. 1. **UniProt accession.** A stable, versioned protein identifier such as P04637 (TP53, human). Entries also have an entry name such as P53_HUMAN. Accessions never change, which is why they make good input keys. 2. **Ensembl gene ID.** A stable gene identifier such as ENSG00000141510. HPA uses this as its primary page key. Note that Ensembl attaches version suffixes (for example ENSG00000141510.17) in some exports, while HPA uses the versionless form. 3. **Gene symbol.** A short name such as TP53. Human-readable but mutable, and the same symbol can refer to different loci over time or in different assemblies. Treat it as a display field, never as a join key. 4. **HPA page address.** HPA gene pages follow the pattern `https://www.proteinatlas.org/-`, for example `https://www.proteinatlas.org/ENSG00000141510-TP53`. Once you hold the Ensembl gene ID and the primary gene symbol, you can construct this URL without any further lookup. The cleanest link is therefore a two-hop path: UniProt accession to Ensembl gene ID to HPA page. UniProt often makes the first hop for you, because reviewed human entries already carry an HPA cross-reference line. The methods below exploit that. ## Method 1. Link a Single Entry from the UniProt Web Interface This is the fastest route when you need one protein right now, and it doubles as a lesson in how to use UniProt's entry pages. 1. Go to `https://www.uniprot.org` and type an accession into the search box, for example `P04637`. Press Enter. The result list shows the entry name (P53_HUMAN), the gene (TP53), and the organism. 2. Open the entry. On the entry page, scroll to the **Cross-references** section. Cross-references are grouped by category, and the Human Protein Atlas link sits in the [gene expression](/blog/guides/gene-expression) group, alongside other expression resources. 3. Click the Human Protein Atlas link. It opens the HPA page keyed by the Ensembl gene ID and gene symbol for that protein, for example `ENSG00000141510-TP53` for TP53. 4. On the HPA page you will find tissue expression (RNA consensus data), protein-level expression from immunohistochemistry, subcellular localization, and pathology panels. Expected outcome for TP53: the UniProt cross-reference points to ENSG00000141510, and the HPA page at `https://www.proteinatlas.org/ENSG00000141510-TP53` loads with tissue and cancer profiles for TP53. If you prefer the flat file view, click **Text** at the top of the UniProt entry. Search the text for a line beginning with `DR ProteinAtlas`. A `DR` line is UniProt's database cross-reference record, and its first field names the external database, the second gives the identifier there. For a reviewed human entry it looks like this: ``` DR ProteinAtlas; ENSG00000141510; TP53. ``` The final field varies between entries, so parse the second field, the Ensembl gene ID, and nothing else. **Check that it worked.** The second field of the `DR ProteinAtlas` line should begin with `ENSG` and should match the Ensembl gene ID shown in the `DR Ensembl` line of the same entry. If the two disagree, one of the cross-references is stale, and you should fall back on ID mapping (Method 2) or HGNC as a tiebreaker. ## Method 2. Batch Linking with the UniProt ID Mapping Tool When you have tens to tens of thousands of accessions, use UniProt's ID mapping service. It converts one identifier type to another through UniProt's internal mapping tables, which include the Ensembl gene ID you need for HPA page construction. ### Step-by-step through the web interface 1. Open `https://www.uniprot.org/id-mapping`. 2. In the **From database** dropdown, choose **UniProtKB AC/ID**. 3. In the **To database** dropdown, choose **Ensembl**. UniProt offers several Ensembl-related targets, so confirm you selected plain Ensembl, which returns Ensembl identifiers for the submitted accessions. 4. Paste your accessions, one per line, into the text box, or upload a file. A small test set: ``` P04637 P04406 O15551 ``` 5. Click **Submit**. The job runs in seconds for small lists. The results page shows a TSV table with your input accession in the left column and mapped Ensembl identifiers on the right. 6. Click **Download** and save the TSV file. One input accession can produce several output rows because one protein can map to more than one Ensembl entry. ### Step-by-step through the REST API The same operation works from the command line or a script. Submit the job: ```bash curl -X POST https://rest.uniprot.org/idmapping/run \ -F 'from=UniProtKB_AC-ID' \ -F 'to=Ensembl' \ -F 'ids=P04637,P04406,O15551' ``` Expected output is a short JSON object carrying a job identifier: ```json {"jobId": "00e97be29ef55a7fb9d3ea04a1ea4bb0b8e21a51"} ``` Poll or stream the finished job: ```bash curl "https://rest.uniprot.org/idmapping/uniprotkb/results/stream/?format=tsv" ``` Expected output shape: ``` From To P04637 ENSG00000141510 P04406 ENSG00000111640 O15551 ENSG00000147872 ``` Then construct HPA URLs from each row: ```python import pandas as pd mapping = pd.read_csv("idmapping.tsv", sep="\t") mapping.columns = ["uniprot_accession", "ensembl_gene_id"] mapping["hpa_url"] = ( "https://www.proteinatlas.org/" + mapping["ensembl_gene_id"] + "-" + mapping["gene_symbol"] ) ``` If your mapping file lacks gene symbols, join a gene name column from UniProt (Method 3) before building URLs. **Why this works.** The Ensembl gene ID is the identifier HPA itself uses to key its gene pages, so a correctly resolved Ensembl gene ID gives a resolvable HPA page by construction. ## Method 3. Pull the Cross-References Directly from the UniProt REST API For a whole proteome or a large fraction of it, skip ID mapping and download the cross-reference columns directly. The UniProt REST API accepts a query, a set of fields, and a format, and returns a TSV you can load into pandas in one call. The query `(organism_id:9606) AND (reviewed:true)` restricts results to human, reviewed entries, that is Swiss-Prot rather than the automatically annotated TrEMBL section. This distinction matters, because reviewed entries carry the curated cross-references you want, and the human reviewed set is on the order of twenty thousand proteins, consistent with the convergence to roughly 20,000 canonical proteins documented across Ensembl and Swiss-Prot annotation history [1]. The API exposes cross-references as fields named with an `xref_` prefix. To retrieve the Ensembl gene IDs and the Human Protein Atlas cross-references together: ```python import io import re import requests import pandas as pd url = ( "https://rest.uniprot.org/uniprotkb/stream" "?query=(organism_id:9606)%20AND%20(reviewed:true)" "&fields=accession,id,gene_primary,xref_ensembl,xref_proteinatlas" "&format=tsv" ) response = requests.get(url, timeout=300) response.raise_for_status() df = pd.read_csv(io.StringIO(response.text), sep="\t") print(df.shape) ``` Expected output is a DataFrame with roughly twenty thousand rows for the reviewed human proteome, and columns whose headers look like: ``` Accession Entry Name Gene Names (primary) Cross-reference (Ensembl) Cross-reference (ProteinAtlas) ``` If the API rejects a field name, the response comes back as a JSON error object with a `messages` array explaining the invalid field, and the correct response is to drop that field and rely on the Ensembl column instead. Constructing the HPA URL from the Ensembl gene ID plus the primary gene symbol is always sufficient, because that pair is the HPA page key. Extract the Ensembl gene ID from the Ensembl cross-reference column. UniProt can store several Ensembl identifiers per entry, and the gene ID is the one matching the `ENSG` prefix: ```python def first_ensg(cell): if pd.isna(cell): return None match = re.match(r"(ENSG\d+)", str(cell)) return match.group(1) if match else None df["ensembl_gene_id"] = df["Cross-reference (Ensembl)"].apply(first_ensg) df["hpa_url"] = ( "https://www.proteinatlas.org/" + df["ensembl_gene_id"] + "-" + df["Gene Names (primary)"] ) df[["Accession", "Gene Names (primary)", "ensembl_gene_id", "hpa_url"]].head(3) ``` Expected output for the first rows: ``` Accession Gene Names (primary) ensembl_gene_id hpa_url 0 P04637 TP53 ENSG00000141510 https://www.proteinatlas.org/ENSG00000141510-TP53 1 P04406 GAPDH ENSG00000111640 https://www.proteinatlas.org/ENSG00000111640-GAPDH 2 O15551 SOD1... ENSG00000147872 https://www.proteinatlas.org/ENSG00000147872-SOD1 ``` **Why one API call beats thousands of page loads.** The same bulk-retrieval pattern underlies serious UniProt-scale analyses. A study of charge distribution across proteomes downloaded and analyzed 551,705 reviewed proteins from Swiss-Prot, computing net charge over 30-residue windows corresponding to the ribosome exit tunnel, which required exactly the kind of batch retrieval this section demonstrates [2]. Fetching entries one at a time through a browser does not scale to that, and the API exists so you never have to. **Check that it worked.** Three checks catch nearly every failure. First, the row count should be close to the canonical human protein count, around twenty thousand, and a wildly different number usually means the `reviewed:true` filter was lost in the query string. Second, at least 95 percent of reviewed human entries should resolve to an `ENSG` ID, so a large number of blanks signals a parsing bug. Third, spot-check two or three constructed URLs in a browser and confirm they open the expected gene page on HPA. ## Method 4. Join from the Human Protein Atlas Side ![Worked example showing how ENSG00000141510.17 is split at the dot to give ENSG00000141510 for the HPA join.](/article-images/illustrations/uniprot-human-protein-atlas-cross-reference-ensembl-strip.webp) Sometimes you start from HPA, for example when you have shortlisted genes by tissue specificity and want UniProt annotations appended. HPA publishes its full annotation set as downloadable TSV files from its download page at `https://www.proteinatlas.org/about/download`. The main proteinatlas table carries, among other columns, the gene symbol and the Ensembl gene ID for every gene profiled. ```python import pandas as pd hpa = pd.read_csv("proteinatlas.tsv", sep="\t") # Strip the Ensembl version suffix if present, so ENSG00000141510.17 becomes ENSG00000141510 hpa["ensg"] = hpa["Ensembl"].astype(str).str.split(".").str uniprot_subset = df[["Accession", "Gene Names (primary)", "ensembl_gene_id"]] merged = uniprot_subset.merge( hpa, left_on="ensembl_gene_id", right_on="ensg", how="inner", ) print(merged.shape) ``` The `how="inner"` join keeps only genes present in both files, which is what you want for a strict cross-reference table. Use `how="left"` if you need to keep all UniProt entries and record which ones lack HPA coverage. The HPA download files also include the classification columns that make the cross-reference analytically useful, such as tissue enrichment categories and protein class. That is what allows the kind of annotation filtering described in the worked example below. ## Choosing Between the Four Methods ![Decision path asking how many accessions you have and whether you start from UniProt or HPA, ending at one of the four methods.](/article-images/illustrations/uniprot-human-protein-atlas-cross-reference-method-triage.webp) | Method | Input | Output | Practical scale | Best for | |--|--|--|--|--| | Entry page cross-reference | One accession | One HPA link | 1 to 10 entries | Quick single-protein lookups | | ID mapping tool | Accession list | Accession to Ensembl TSV | 10 to 100,000 | Mixed lists, one-off batch jobs | | REST API bulk export | A query | Full table with xref columns | Whole proteome | Reproducible pipelines | | HPA download join | HPA TSV file | Merged annotation table | Whole proteome | HPA-first analyses | In practice, most projects settle on the API export as the backbone, with the ID mapping tool reserved for ad hoc lists that arrive mid-project. ## A Worked End-to-End Example: Secreted Biomarker Candidates To see the cross-reference earning its keep, consider the standard biomarker triage pattern: find genes upregulated in tumor tissue, keep only those whose products are secreted or otherwise accessible outside the cell, then check tissue specificity to avoid candidates expressed in essential normal tissues. A published prostate cancer study followed precisely this logic. Starting from the expression dataset GSE55945 with 13 prostate tumors and 8 normal samples, the authors identified differentially expressed genes at a threshold of absolute log2 fold change greater than 1 and adjusted p less than 0.05, then filtered the upregulated genes for secreted proteins using annotations from the Human Protein Atlas and UniProt databases. Out of 243 differentially expressed genes, five upregulated candidates encoding secretory proteins survived the filter, and SPON2 and MSMB proceeded to diagnostic validation with strong discrimination between tumor and normal serum samples [3]. Reproducing the annotation-filtering step is now straightforward with the table you built in Methods 3 and 4. From the merged table, filter on the UniProt subcellular location annotation and the HPA protein class column for secreted categories, then restrict to the genes flagged as upregulated in your differential expression step. The join key is the Ensembl gene ID on both sides, which is why the whole exercise stays reproducible. The same cross-referencing discipline extends to proteomics search databases. A recent proteomic profiling study of early-stage non-small cell lung cancer, covering 351 stage I patients in the discovery cohort with an additional 103 validation participants, searched its LC-MS/MS data with DIA-NN against the human UniProt database and identified 4,260 differentially expressed proteins, a workflow in which every identified protein is already keyed by a UniProt accession ready for HPA linkage [4]. And when a modeling study needs to confirm that predicted binding-site residues are real annotated sequence features, it verifies the remaining residues against the UniProt database, as one SARS-CoV-2 [spike protein](/blog/guides/spike-protein) modeling analysis did before comparing computational pruning strategies [5]. In each case, holding a verified accession-to-Ensembl mapping turns a list of protein hits into a browsable set of tissue and pathology pages in minutes. ## Checking and Validating Your Cross-Reference Table Run these checks before you trust the merged table. 1. **Uniqueness.** Group by UniProt accession and count rows. More than one row per accession means that entry carried multiple Ensembl gene IDs. Decide explicitly whether to keep all mappings, keep the first, or flag them for manual review. Silent deduplication hides biology. 2. **Reverse uniqueness.** Group by Ensembl gene ID. One gene can host more than one reviewed UniProt entry when isoforms or cleaved products are separate entries. This is expected, but it will double-count genes in downstream summaries if you forget it. 3. **Round-trip spot check.** Pick ten random rows. Open each UniProt entry, read its `DR ProteinAtlas` line, and compare against your constructed HPA URL. They should agree. 4. **Coverage estimate.** The fraction of reviewed human entries with an HPA cross-reference should be high, because HPA antibody coverage in Swiss-Prot is used as supporting evidence for protein existence [1]. A suspiciously low fraction usually means a parsing error, not a biology gap. 5. **URL resolution.** A scripted HEAD request against a random sample of your constructed HPA URLs should return HTTP 200. Persistent 404s point at malformed URLs, most often a versioned Ensembl ID or a whitespace-contaminated gene symbol. ```python import requests sample = merged.sample(10, random_state=1) for u in sample["hpa_url"]: status = requests.head(u, allow_redirects=True, timeout=30).status_code print(status, u) ``` ## Common Mistakes and Limitations **Using gene symbols as the join key.** This is the most common and most damaging error. Symbols are renamed, reused across loci, and ambiguous between species. HGNC, the Human Gene Nomenclature Committee, is the authority for current symbols, and the fact that hundreds of Swiss-Prot entries were classified as non-coding by HGNC biotypes in one cross-database audit shows how much slippage exists even between expertly curated resources [1]. Always map through accessions and Ensembl gene IDs. **Leaving Ensembl version suffixes in the key.** `ENSG00000141510.17` will not match `ENSG00000141510` in a string join. Strip the suffix on both sides before merging. **Assuming the mapping is one-to-one.** It is not, in either direction. Plan your duplicate policy before the join, not after you see the row counts explode. **Mixing reviewed and unreviewed UniProt entries.** TrEMBL entries lack the curated cross-references and have heavier redundancy. Unless you deliberately need predicted proteins, filter with `reviewed:true`. **Treating a missing HPA link as a data error.** Some entries lack HPA cross-references because antibodies have not been generated or validated for that target, not because the gene does not exist. The persisting spread in canonical protein counts across annotation portals, from 21,819 down to 18,891 across nine portals in early 2017, is a reminder that coverage boundaries differ by design and by evidence policy [1]. Record the missing link as missing coverage and move on. **Ignoring HPA's own evidence tiers.** HPA grades how well antibody-based staining is supported. An expression claim carried by a weakly validated antibody is a weaker claim. Read the reliability annotation on the HPA page before you cite a tissue pattern as fact. **Ignoring version drift.** UniProt releases on a regular cadence and HPA updates continuously. Record the UniProt release number and the HPA download date in your methods section or a metadata file next to the data. Results that cannot be tied to database versions cannot be reproduced. **Exceeding polite API usage.** Large REST queries should use the bulk `stream` endpoint rather than thousands of individual requests. If you receive HTTP 429 responses, back off and batch your queries rather than retrying in a tight loop. One general limitation applies to everything above. Cross-references describe database records, not your specific experiment. Individual protein targets still need interpretation in the context of your own assay, sample type, and validation data. ## Frequently Asked Questions ### What is the fastest way to link one UniProt entry to its Human Protein Atlas page? Open the entry on uniprot.org, find the Human Protein Atlas link in the Cross-references section, and click it. For construction from scratch, resolve the Ensembl gene ID and build the URL in the form `https://www.proteinatlas.org/ENSG_ID-GENE`. ### Does UniProt store a direct cross-reference to the Human Protein Atlas? Yes. Reviewed human entries carry a `DR ProteinAtlas` cross-reference line pointing to the corresponding HPA gene page, and the link is also visible in the web interface under Cross-references. ### Why do some UniProt entries have no Human Protein Atlas link? Usually because HPA has no validated antibody or no published profile for that gene, or because the entry is not part of the reviewed human set. Treat the absence as a coverage boundary rather than an error. ### Can I use gene names instead of accessions to match the two databases? You can, but you should not rely on them. Symbols change over time and can collide, so use accessions and Ensembl gene IDs as keys and keep gene names as display columns. ### How do I batch-map thousands of UniProt accessions to HPA? Use the UniProt ID mapping tool at uniprot.org/id-mapping or its REST endpoint, with UniProtKB_AC/ID as the source and Ensembl as the target, then construct HPA URLs from the returned Ensembl gene IDs. ### Is the UniProt-to-HPA mapping one-to-one? No. A UniProt entry can map to multiple Ensembl gene IDs and one gene can carry multiple reviewed UniProt entries, so count duplicates on both sides and set an explicit policy before merging. ### Which identifier should I use as the join key? The versionless Ensembl gene ID, stripped of any version suffix, is the most reliable join key because it is stable, unique to a locus, and the identifier HPA itself uses to key gene pages. ### Do UniProt and the Human Protein Atlas update at the same time? No. UniProt publishes numbered releases on a schedule and HPA updates continuously, so record the UniProt release and the HPA download date whenever you publish or share a cross-referenced table. ## Sources 1. [Last rolls of the yoyo: Assessing the human canonical protein count.](https://pubmed.ncbi.nlm.nih.gov/28529709/) 2. [Protein charge distribution in proteomes and its impact on translation.](https://pubmed.ncbi.nlm.nih.gov/28531225/) 3. [Immunodiagnostic profiling of SPON2 and MSMB as biomarkers in prostate cancer for nanomaterial- based detection strategies.](https://pubmed.ncbi.nlm.nih.gov/41200187/) 4. [Proteomic profiling of early-stage non-small cell lung cancer identifies a high-performance protein signature associated with postoperative recurrence.](https://pubmed.ncbi.nlm.nih.gov/41581312/) 5. [SP-A binding to the SARS-CoV-2 spike protein using hybrid quantum and classical in silico modeling and molecular pruning by Quantum Approximate Optimization Algorithm (QAOA) Based MaxCut with ZDOCK.](https://pubmed.ncbi.nlm.nih.gov/36189278/)