# UniProt ID Mapping Not Working? Common Fixes

If your UniProt ID mapping job returns nothing, the most likely cause is a mismatch between the identifiers you submitted and the source database you selected in the "from" field. The single fastest check is this: open your input file, look at one identifier, and ask whether it is a UniProt accession (P04637), a UniProt entry name (P53_HUMAN), a gene symbol (TP53), an Ensembl ID (ENSP00000269405), or a RefSeq accession (NP_000537). Then confirm that the "from" database in the mapping form or API call matches exactly what you have. A list of gene symbols submitted against "UniProtKB AC/ID" returns zero results, and a list of accessions submitted against "Gene_Name" behaves just as badly.

This guide walks through every common failure mode of the UniProt Retrieve/ID Mapping tool, in order from most frequent to rarest. Each fix explains the mechanism behind the failure so you can recognize the same problem in a slightly different disguise. The UniProt Retrieve/ID Mapping tool exists specifically to take a list of identifiers, retrieve the corresponding UniProtKB entries, and convert identifiers between UniProt and external databases in either direction [1]. When it fails, the reason is almost always in the input, the selected databases, or the assumptions you bring about how identifiers behave.

## Start Here: The 60-Second Diagnostic Sequence

![Decision path that sorts a failed UniProt mapping job by identifier type, formatting damage, and stale accessions before deeper fixes.](/article-images/illustrations/uniprot-id-mapping-not-working-triage-zero-results.webp)

Work through these checks before anything else. Most sessions end at step 3.

1. Open your identifier list in a plain text editor, not Excel. Look for stray quotation marks, trailing whitespace, tab characters, or full protein sequences pasted by accident.
2. Classify one identifier by eye. Six characters starting with a letter, an underscore, and digits or an underscore pattern (P04637, P53_HUMAN) points to UniProt. ENSG or ENSP prefixes point to Ensembl. NP_ or XP_ prefixes point to RefSeq. Plain words like TP53 or ACTB point to gene names.
3. Compare that classification with the "from" database dropdown on the UniProt ID mapping page, or the "from" parameter in your API call. They must match character for character in spirit. "UniProtKB AC/ID" is not the same choice as "UniParc" or "UniRef100".
4. Check case. UniProt accessions are case sensitive in practice for the letter prefix convention, and entry names are uppercase. Gene symbols are uppercase. Mixed-case input usually signals a copy-paste artifact.
5. Check for one-to-many identifiers, such as P04637-2, which is an isoform identifier rather than a canonical entry, or versioned RefSeq accessions like NP_000537.2, where the .2 suffix can break exact matching.
6. Submit a three-line test file with identifiers you know exist, such as P04637, P02768, and P69905. If the test file maps, your problem is in the data. If the test file also fails, your problem is in the tool selection, the network, or the API call.

This sequence resolves the majority of "uniprot id mapping not working" complaints before any deeper investigation is needed. The rest of this article covers what to do when it does not.

## How UniProt ID Mapping Actually Works

Understanding the mechanism makes every fix below obvious rather than memorized. UniProt consists of several components. The UniProt Knowledgebase (UniProtKB) holds the annotated protein entries, split into the manually curated UniProtKB/Swiss-Prot section and the computationally annotated UniProtKB/TrEMBL section. The UniProt Archive (UniParc) stores every publicly available [protein sequence](/blog/guides/protein-sequence) together with the history of that sequence and links back to the source databases. UniRef clusters merge sequences that are 100, 90, or 50 percent identical to speed up similarity searches [2].

The mapping service is protein centric. It was built to establish links between biological databases as an essential first step for integrating molecular data and attaching functional annotations, and it has covered on the order of 90 distinct identifier types drawn from databases of genes, proteins, pathways, diseases, structures, protein families, interactions, literature, and ontologies, with regular updates running since 2006 [3]. On the website, the Retrieve/ID Mapping tool takes your list, looks up each identifier in the selected source database, follows the cross-references stored on those entries, and returns entries from the target database you selected [1] [4].

Three consequences of this design cause most confusion:

- Mapping follows cross-references, not a fixed dictionary. If a cross-reference is absent, stale, or restricted by organism, the mapping silently drops that row.
- UniParc ties everything together by sequence identity rather than by name. Services built on UniParc, such as PICR, return mappings only where sequences match at 100 percent identity, which is strict by design [5].
- Identifiers themselves are unstable over time. Accessions get merged, demerged, and retired as annotations change, which is a core reason the field needed dedicated mapping infrastructure in the first place [5] [2].

A concrete example of why this matters in practice: pipelines like Mut-Map take a UniProt ID as the entry point and chain it through PDB structures, AlphaFold models, residue renumbering, and mutation overlays [6]. Vaccine design pipelines similarly anchor their entire subtractive proteomics workflow on three UniProt accession numbers for candidate antigens [7]. When the anchor identifier is stale or ambiguous, every downstream step inherits the error. That is the cost of getting ID mapping wrong, and it justifies spending a few minutes on diagnostics.

## Troubleshooting Table: Symptoms, Causes, and Fixes

This table is the core of the article. Find your symptom in the left column, then jump to the detailed fix section named in the last column.

| Symptom | Likely cause | How to confirm | Fix |
|--|--|--|--|
| Zero results, no errors | Wrong "from" database selected | Classify one identifier by prefix and pattern | Fix 1, section below |
| Zero results for some rows only | Obsolete, merged, or deleted accessions | Search the accession directly on uniprot.org | Fix 3 |
| Error about invalid identifiers | Formatting artifacts from Excel or copy-paste | View file in a plain text editor | Fix 2 |
| Results include hundreds of rows you never submitted | Gene name mapping is many to many | Check the mapped-to column for repeats | Fix 4 and Fix 5 |
| Results lack the organism you expected | No taxonomic restriction applied | Filter results by organism, then recount | Fix 5 |
| Mapped genes disagree with a previous run or another tool | Cross-reference updates between releases, or genuine resource disagreement | Re-run a fixed subset and compare | Fix 3 and the resource comparison section |
| API returns 404 or an empty job | Wrong endpoint, wrong parameter names, or job failed silently | Print the HTTP status and job status response | Fix 6 |
| Identifier exists but no mapping is offered | No cross-reference of the target type exists on that entry | Open the entry page and inspect cross-references | Fix 1 and Fix 7 |
| Identifier maps to a sequence that is clearly a different protein | Historical cross-reference attached to a merged entry | Verify by sequence with BLAST or PICR | Fix 7 |

## Fix 1: Wrong Source Database Selected

This is the most common cause of uniprot id mapping not working, and it accounts for the classic zero-result job. The Retrieve/ID Mapping tool requires two database selections, a "from" database that describes what you have and a "to" database that describes what you want [1] [4]. The dropdown includes choices such as UniProtKB AC/ID, UniParc, UniRef100, Gene Name, Ensembl, RefSeq Protein, PDB, and dozens more [1] [3].

The failure modes are predictable:

- You have gene symbols like TP53 but selected "UniProtKB AC/ID". Zero results, because no accession named TP53 exists.
- You have accessions like P04637 but selected "Gene_Name". Zero results, because gene name lookups expect symbols.
- You have Ensembl protein IDs like ENSP00000269405 but selected "RefSeq Protein". Zero results.
- You have an entry name like P53_HUMAN but the dropdown only accepts accessions for that source type, or vice versa depending on the option you chose.

How to fix it. Classify your identifiers before submitting. UniProt accessions are six characters, typically one letter, one digit, one letter, then four alphanumeric characters in the legacy format, with newer formats described in UniProt documentation. Entry names consist of an abbreviation, an underscore, and a species mnemonic, such as P53_HUMAN. Ensembl IDs start with ENS followed by a species letter and a type letter. RefSeq protein accessions start with NP_, XP_, APZ, or similar two-letter-plus-underscore or plain prefixes. Once you know what you have, pick the matching "from" database. If your list mixes types, split it into separate files and run one mapping job per type. Mixed lists force you into the weakest mapping path and make results impossible to audit.

If you are unsure what an identifier is, paste a single one into the search bar on uniprot.org. A direct search resolves the identifier across UniProtKB, UniParc, and UniRef and tells you what the identifier actually is before you commit to a batch job [1].

## Fix 2: Formatting Problems in Your Identifier List

The second most common cause is invisible formatting damage, and the usual culprit is a spreadsheet program. Excel and its relatives convert plain text through several destructive filters. They strip leading characters that look like numeric zeros, they reinterpret long digit strings into scientific notation, they add curly quotation marks when you paste from formatted documents, and they silently append carriage returns on Windows systems. Any of these turns a valid identifier into an invalid one, and the mapper reports the row as unparseable or unresolvable.

A second formatting trap is the delimiter. The UniProt web tool expects identifiers separated by newlines, spaces, or commas in the paste box, but files exported from some pipelines arrive with semicolons, pipe characters copied from FASTA headers, or mixed delimiters. A list copied from a FASTA file often includes the full header text, such as sp|P04637|P53_HUMAN, rather than the bare accession P04637. Interestingly, in this one case the mapper may still succeed because UniProt and many downstream tools recognize the familiar FASTA header format, but relying on that is fragile. Clean the list instead.

Diagnostic procedure:

1. Open the file in a plain text editor such as Notepad, TextEdit in plain text mode, nano, or vim. Never debug identifier files in a spreadsheet.
2. Confirm one identifier per line, no leading or trailing whitespace, no quotes, no version suffixes unless you intend them, and no extra columns.
3. Count the lines. If your file claims 500 proteins but has 499 or 501 lines, a formatting problem already exists.
4. Remove duplicates and blank lines. Blank lines are a frequent silent cause of partial failures.
5. Save as plain UTF-8 text with Unix-style line endings when working cross-platform.

For readers learning how to use UniProt for the first time, the official protocols for the Retrieve/ID Mapping tool recommend pasting or uploading a clean list of identifiers and verifying the returned entry count against your submitted count as a standard quality step [1] [4]. Make that comparison a habit. If you submitted 500 and received 493 mapped entries, the seven missing rows are the real finding, not a rounding error.

## Fix 3: Obsolete, Merged, and Deleted Accessions

Protein identifiers are not stable forever, and this is by design rather than accident. As the PICR authors put it, each major [protein database](/blog/guides/protein-database) uses its own conventions when assigning identifiers, and resolving the various, potentially unstable identifiers that refer to identical proteins is a major challenge when unifying datasets across sources [5]. UniProt handles this instability with explicit lifecycle states, and each state breaks mapping in a different way.

When two UniProtKB entries are judged to describe the same protein, one accession is merged into the other. The old accession still resolves to the surviving entry, so mapping often still works. When an entry is split, for example because a protein was reannotated as two distinct gene products, one accession demerges into several new accessions. Mapping may return multiple targets. When an entry is removed entirely, as happens routinely with redundant TrEMBL entries at each release, the accession can stop resolving to a current UniProtKB entry, and the mapping row disappears or the identifier lands in the "unmapped" bucket that the tool and the API report back to you [1] [8].

How to confirm and fix:

1. Paste the failing accession into the uniprot.org search bar. If the entry was merged, UniProt shows the redirect and the surviving accession. Use the surviving accession from now on.
2. If the search returns nothing, the identifier may exist only in UniParc, which stores the sequence history and links to source databases even for sequences no longer in UniProtKB [2]. In that case, take the sequence from UniParc and switch to a sequence-based approach, covered in Fix 7.
3. For manuscripts and pipelines, record the UniProt release version or the date you ran the mapping. A mapping performed against one release is not guaranteed to reproduce exactly against a later release, because cross-references and entry states change.
4. If your input came from an old paper or an old version of another database, expect a fraction of accessions to be stale. Budget for it. In one large proteomics benchmark, mapping resources were tested against 11,879 distinct UniProt accessions generated from mass spectrometry runs, and the authors confirmed a high level of discrepancy among the mapping resources they compared [9]. Stale input identifiers were one of the structural reasons mapping outcomes varied.

The habit that prevents this failure is simple. Whenever a mapping job reports unmapped identifiers, treat those identifiers as data, not as noise. Export them, investigate each one, and replace them with current accessions before the next run.

## Fix 4: Gene Names Are Not Identifiers

Gene symbols look like identifiers and behave like search terms, but they are neither unique nor stable. The same symbol can refer to different genes in different organisms. The same gene can carry several symbols across nomenclature updates. Symbols can be ambiguous abbreviations shared between a gene name and something else entirely. When you map gene names through UniProt, the service does its best against the Gene_Name cross-references, but you inherit all of that ambiguity.

The visible symptoms are a result set that is larger than your input, target entries from the wrong organism, and gene symbols that map to protein families rather than the specific protein you meant. The mapping itself is functioning correctly. Your input is simply under-specified.

How to fix gene name mapping:

1. Always restrict by organism. The UniProt website and API both support adding a taxonomy filter to the mapping job, so a search for a symbol can be scoped to human, mouse, or your study species rather than returning matches across all of life [1] [8].
2. Prefer a more specific upstream identifier whenever one exists. If your source data carries Ensembl gene IDs, Ensembl protein IDs, or RefSeq accessions, map from those instead of from symbols. The mapping chain Ensembl to UniProt is anchored to defined sequences and is far less ambiguous than symbol to UniProt.
3. Spot-check a random sample of mapped results. Open five mapped entries and confirm the gene, the organism, and the protein length match your expectations. This five-minute check catches the majority of silent mis-mappings.
4. Review the publication and identification confidence of your own input. If a gene symbol originated from a low-confidence annotation in your source platform, no mapping tool can rescue it.

Readers who need a structured walkthrough of the tool, including the organism-restriction options and batch retrieval behavior, will find the official current protocols useful as a general uniprot database tutorial, with step-by-step coverage of BLAST, Align, Peptide Search, and Retrieve/ID Mapping [1].

## Fix 5: One-to-Many and Many-to-Many Results

A related complaint looks like the opposite failure. Instead of missing rows, you get too many rows. You submit 200 identifiers and receive 900 mapped results. Nothing is broken. Identifier mapping is inherently non one-to-one, for three reasons.

First, a single UniProt entry cross-references many external database entries, and an external entry can cross-reference several UniProt entries, for example when isoforms or closely related entries both carry the same external link. Second, gene-name mappings fan out as described in Fix 4. Third, cross-references to databases that themselves have one-to-many structures, such as PDB entries covering single chains of a multi-chain structure, multiply on the target side.

The practical fixes:

1. Decide in advance what your unit of analysis is. If you need one row per input identifier, aggregate the mapping results by input identifier and keep either all targets or a single best target under a rule you define and document.
2. Use taxonomic restriction to remove the largest source of fan-out, cross-species matches [5].
3. Use the "Reviewed" filter, selecting UniProtKB/Swiss-Prot only, when you want manually curated targets instead of the full TrEMBL space. The Swiss-Prot versus TrEMBL distinction is a core design feature of UniProtKB [2], and choosing the reviewed subset usually shrinks results dramatically and raises confidence.
4. Never assume that row order in the output matches your input order. Join results back to your original table by identifier, not by position. This single habit prevents a whole class of silent data corruption errors in downstream merging.

This join-by-identifier rule also protects you when you later switch tools. An independent comparison of three mapping resources found a high level of discrepancy among them and showed that resource choice measurably affected downstream proteome-transcriptome correlations [9]. If your merged table was assembled by row position from one tool's output, switching tools would corrupt it silently. If it was assembled by identifier, the difference between tools becomes visible and auditable instead.

## Fix 6: API and Script Failures

![Flowchart of the UniProt ID mapping API: POST the ids, poll the status endpoint, then fetch results, with error branches.](/article-images/illustrations/uniprot-id-mapping-not-working-api-job-flow.webp)

Many readers run mapping programmatically, and the failure mode shifts from wrong dropdowns to wrong endpoints and parameter names. The UniProt REST API powers the uniprot.org website itself and exposes UniProtKB, UniRef, UniParc, Proteomes, and the ID Mapping tool, along with supporting controlled vocabularies, returning results in multiple downloadable formats [8]. The service handles enormous traffic, on the order of 303 million requests per month on average over the year reported in 2025, so transient capacity problems are rare [8]. When a script fails, look first at your own request.

The common API mistakes:

1. Using the wrong HTTP method. Job submission for ID mapping is a POST with form fields named from, to, and ids. A GET to the submission endpoint returns an error.
2. Misnaming parameters. The parameter that carries your identifiers is called ids, plural, and the values are comma separated within that single parameter.
3. Not polling for job completion. The ID mapping endpoint is asynchronous. Submission returns a job identifier, results are not immediately available, and your script must poll the status endpoint until the job finishes before fetching results [8].
4. Fetching results with the wrong job identifier, or mixing up the job ID from one run with the results URL of another.
5. Exceeding request sizes with very large lists in a single call. Batch your input rather than assuming any size is accepted.
6. Ignoring HTTP status codes. A 404 or 400 response printed to console answers the question faster than any amount of output-file inspection.

A minimal, correct Python pattern using the requests library looks like this:

```python
import time
import requests

ids = ["P04637", "P02768", "P69905"]

submit = requests.post(
    "https://rest.uniprot.org/idmapping/run",
    data={"from": "UniProtKB_AC-ID", "to": "Gene_Name", "ids": ",".join(ids)},
)
submit.raise_for_status()
job_id = submit.json()["id"]

while True:
    status = requests.get(
        "https://rest.uniprot.org/idmapping/status/" + job_id
    ).json()
    if status.get("jobStatus") == "FINISHED":
        break
    if "results" in status or status.get("jobStatus") == "ERRORED":
        break
    time.sleep(3)

results = requests.get(
    "https://rest.uniprot.org/idmapping/stream/results/"
    + job_id
    + "?format=tsv"
).text
print(results)
```

The API documentation page on uniprot.org generates example snippets in several programming languages, which is the fastest way to get a working pattern for your language of choice and to confirm current parameter names [8]. If your script worked last month and fails now, re-check the endpoint names against the current documentation, because the service surface evolves with the website it powers.

One more API-era tip. Older tutorials and Stack Overflow answers sometimes reference legacy mapping endpoints from the pre-2022 website. Those code fragments are a frequent cause of uniprot id mapping not working in new scripts. Prefer the endpoints and snippet generators in the official API documentation [8].

## Fix 7: When Nothing Maps, Use the Sequence

Sometimes the identifier is simply gone or was never resolvable, and the only reliable handle you have left is the protein sequence itself. UniProt gives you three sequence-based escape hatches, and a fourth from a companion service.

First, BLAST. The UniProt BLAST tool performs sequence similarity search against UniProtKB, and the official protocols cover both the basic workflow and alternate routes through search results pages and the basket [1]. If an accession is dead, BLASTing its sequence finds the current entry that carries the same or a near-identical sequence, with an alignment you can eyeball. For dead TrEMBL entries this is often the fastest recovery path.

Second, Peptide Search. This tool retrieves proteins containing a short peptide sequence, which is useful when you have only a fragment, for example a tryptic peptide from a mass spectrometry result, rather than a full-length sequence [1]. It is also a sanity check that a peptide you believe belongs to protein X actually appears in the entry you mapped it to.

Third, PICR. The Protein Identifier Cross-Reference service uses UniParc as a warehouse and offers cross-references based on 100 percent sequence identity to proteins from over 70 distinct source databases, through both an interactive interface and programmatic SOAP and REST access. Users can paste identifiers or upload FASTA sequences, and results can be limited by source database, taxonomic ID, and the activity status of the entry in the source database [5]. That activity-status filter is PICR's answer to the obsolete-identifier problem, because it lets you exclude inactive source entries from the mapping output. If your identifier-based mapping is failing because of identifier churn, sequence identity through PICR sidesteps churn entirely.

Fourth, keep the mapping itself but change the anchor. If a pipeline like Mut-Map depends on a UniProt ID as its entry point into structure mapping and mutation overlay [6], and that ID has gone stale, resolve the sequence first with BLAST or PICR, obtain the current accession, and then feed the pipeline. Re-anchoring on the sequence costs a few minutes and restores reproducibility.

## Why Different Mapping Tools Give Different Answers

A recurring frustration is that UniProt ID mapping, DAVID, EnVision, NetAffx, and other services produce different results for the same input. This is expected, and the discrepancy has been measured. In the endometrial cancer proteomics study cited above, three freely available internet-based mapping resources were compared for converting UniProt accessions to Affymetrix probeset identifiers across samples that generated 11,879 distinct accessions, and the comparison confirmed a high level of discrepancy among the resources, with mapping quality affecting downstream proteome-transcriptome correlations [9].

The sources of discrepancy are structural:

- Different underlying databases and update schedules. Each service snapshots its cross-references at its own cadence [5].
- Different mapping philosophies. Sequence-identity-based services such as PICR enforce 100 percent identity and can restrict by taxonomy and activity status [5], while cross-reference-based services follow whatever links each entry currently carries [3].
- Different scope. Some services are species or technique specific, which was one of the motivations for building broader services in the first place [5] [3].
- Different handling of one-to-many links and of obsolete identifiers.

The operational consequence is that you should pick one primary mapping resource per project, document it and its version, and treat mappings from a second resource as validation rather than as ground truth. If two resources agree on a mapping, confidence rises. If they disagree, investigate that row individually instead of averaging the disagreement away. Day and colleagues showed that downstream correlations can be used to evaluate mapping quality in integrative studies [9], and the general principle transfers: evaluate your mapping against an independent biological signal when one exists.

## Common Mistakes and Limitations

These are the errors seen repeatedly in real project consultations.

- Assuming identifiers are permanent. Merges, demerges, and deletions are normal lifecycle events in UniProtKB. Any pipeline that hardcodes accessions without recording the mapping date will break eventually.
- Treating gene symbols as unique keys. Symbols are ambiguous across organisms and unstable across nomenclature updates. Restrict by organism and prefer sequence-anchored identifiers whenever available [1].
- Joining tables by row position. Mapping output is not guaranteed to preserve input order or cardinality. Always join by identifier.
- Ignoring the unmapped bucket. The identifiers that fail to map are often the most informative rows in the job, flagging stale input, wrong organism assumptions, or genuine data problems.
- Copying FASTA headers instead of accessions. The header sp|P04637|P53_HUMAN is not an accession. Parsing it into parts is trivial and makes your mapping auditable.
- Mapping without recording the release. Reproducibility requires recording which UniProt release, which from and to databases, and which taxonomic filters you used.
- Expecting one tool to be a universal oracle. Discrepancies among mapping resources are real and measurable [9], and sequence-identity mapping [5] is a different contract from cross-reference mapping.
- One limitation worth stating plainly. Identifier mapping choices are analysis decisions, not mechanical steps. Two defensible choices of source database or target subset can produce different but both legitimate results, and the correct choice depends on your biological question. For the specific clinical or diagnostic context of individual patient data, that interpretation belongs with a qualified professional in that domain, not with an automated mapping step.

## Prevention Practices for Reproducible Mapping

The fixes above become unnecessary when a few habits are in place from the start of a project.

1. Canonicalize identifiers at ingestion. The moment data enters your project, classify each identifier, map it once to a current UniProt accession, and store both the original and the mapped value with the UniProt release used.
2. Record provenance for every mapping. Capture the from database, the to database, taxonomic filters, the UniProt release or date, and the tool or API version [1] [8] [3].
3. Keep your raw identifier lists immutable. Mapping results are derived data. If a release change alters mappings, you re-run from the immutable originals rather than trying to patch a partially mapped table.
4. Fail loudly on cardinality changes. Add an assertion to scripts that compares submitted counts with returned counts, and halt or flag when they differ.
5. Prefer sequence anchors for long-lived pipelines. For anything that must survive years, store the sequence alongside the accession. Sequence identity through UniParc-based services remains a stable recovery path even after identifier churn [5] [2].
6. Re-run mappings at defined project milestones rather than continuously. Continuous remapping creates moving targets for downstream collaborators, while milestone re-runs create explicit, reviewable updates.
7. When publishing, state the mapping resource and date in the methods. Reviewers and readers can then reproduce your identifier space, which the field's documented instability makes essential [5].

## Frequently Asked Questions

### Why does UniProt ID mapping return nothing for my list?

The most common reason is a mismatch between your identifiers and the "from" database you selected, for example gene symbols submitted against UniProtKB AC/ID. Classify one identifier by its prefix and pattern, then select the matching source database and re-run.

### Why did my UniProt accession stop working after a database update?

Accessions can be merged into another entry, demerged into several entries, or removed entirely as annotation evolves. Search the accession directly on uniprot.org to find its redirect or its sequence in UniParc, then switch to the current accession or use a sequence-based method such as BLAST.

### Can UniProt map gene names to UniProt accessions reliably?

Only with organism restriction and spot-checking, because gene symbols are ambiguous and change over time. Whenever your source data offers Ensembl or RefSeq identifiers, map from those instead, since they anchor to defined sequences.

### Why do I get more results than identifiers I submitted?

Identifier mapping is many-to-many, because one entry can carry multiple cross-references and one external identifier can link to several UniProt entries. Decide your unit of analysis, restrict by organism and reviewed status, and aggregate results by input identifier rather than by row order.

### How do I run ID mapping in Python or R?

Use the UniProt REST API, which powers the uniprot.org website and exposes the ID Mapping tool. Submit a POST with from, to, and ids parameters, poll the status endpoint until the job finishes, then fetch results, and use the API documentation page to generate snippets in your language [8].

### What is the difference between UniProtKB, UniParc, and UniRef?

UniProtKB holds annotated entries in the manually curated Swiss-Prot section and the automatically annotated TrEMBL section. UniParc stores all publicly available protein sequences with their source database history. UniRef clusters merge sequences at 100, 90, and 50 percent identity to speed similarity searches [2].

### My IDs map but to the wrong organism, how do I fix that?

Apply a taxonomy filter to the mapping job, available both on the website and through the API [1] [8]. If cross-species matches persist, your input identifiers are probably ambiguous gene symbols, and you should switch to sequence-anchored identifiers or verify candidates by sequence.

### Is there an alternative to UniProt ID mapping?

Yes. PICR maps identifiers and sequences against over 70 source databases using 100 percent sequence identity through UniParc, with filters for taxonomic ID and activity status [5]. For failures caused by identifier churn, sequence-based mapping through PICR or UniProt BLAST is often the most robust path [5] [1].

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Why does UniProt ID mapping return nothing for my list?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "The most common reason is a mismatch between your identifiers and the from database you selected, for example gene symbols submitted against UniProtKB AC/ID. Classify one identifier by its prefix and pattern, then select the matching source database and re-run."
      }
    },
    {
      "@type": "Question",
      "name": "Why did my UniProt accession stop working after a database update?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Accessions can be merged into another entry, demerged into several entries, or removed entirely as annotation evolves. Search the accession directly on uniprot.org to find its redirect or its sequence in UniParc, then switch to the current accession or use a sequence-based method such as BLAST."
      }
    },
    {
      "@type": "Question",
      "name": "Can UniProt map gene names to UniProt accessions reliably?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Only with organism restriction and spot-checking, because gene symbols are ambiguous and change over time. Whenever your source data offers Ensembl or RefSeq identifiers, map from those instead, since they anchor to defined sequences."
      }
    },
    {
      "@type": "Question",
      "name": "Why do I get more results than identifiers I submitted?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Identifier mapping is many-to-many, because one entry can carry multiple cross-references and one external identifier can link to several UniProt entries. Decide your unit of analysis, restrict by organism and reviewed status, and aggregate results by input identifier rather than by row order."
      }
    },
    {
      "@type": "Question",
      "name": "How do I run ID mapping in Python or R?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Use the UniProt REST API, which powers the uniprot.org website and exposes the ID Mapping tool. Submit a POST with from, to, and ids parameters, poll the status endpoint until the job finishes, then fetch results, and use the API documentation page to generate snippets in your language."
      }
    },
    {
      "@type": "Question",
      "name": "What is the difference between UniProtKB, UniParc, and UniRef?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "UniProtKB holds annotated entries in the manually curated Swiss-Prot section and the automatically annotated TrEMBL section. UniParc stores all publicly available protein sequences with their source database history. UniRef clusters merge sequences at 100, 90, and 50 percent identity to speed similarity searches."
      }
    },
    {
      "@type": "Question",
      "name": "My IDs map but to the wrong organism, how do I fix that?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Apply a taxonomy filter to the mapping job, available both on the website and through the API. If cross-species matches persist, your input identifiers are probably ambiguous gene symbols, and you should switch to sequence-anchored identifiers or verify candidates by sequence."
      }
    },
    {
      "@type": "Question",
      "name": "Is there an alternative to UniProt ID mapping?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Yes. PICR maps identifiers and sequences against over 70 source databases using 100 percent sequence identity through UniParc, with filters for taxonomic ID and activity status. For failures caused by identifier churn, sequence-based mapping through PICR or UniProt BLAST is often the most robust path."
      }
    }
  ]
}
</script>

## Sources

1. [UniProt Tools: BLAST, Align, Peptide Search, and ID Mapping.](https://pubmed.ncbi.nlm.nih.gov/36943033/)
2. [The Universal Protein Resource (UniProt): an expanding universe of protein information.](https://pubmed.ncbi.nlm.nih.gov/16381842/)
3. [A comprehensive protein-centric ID mapping service for molecular data integration.](https://pubmed.ncbi.nlm.nih.gov/21478197/)
4. [UniProt Tools.](https://pubmed.ncbi.nlm.nih.gov/27010333/)
5. [The Protein Identifier Cross-Referencing (PICR) service: reconciling protein identifiers across multiple source databases.](https://pubmed.ncbi.nlm.nih.gov/17945017/)
6. [Mut-Map: Comprehensive Computational Pipeline for Structural Mapping and Analysis of Cancer-Associated Mutations.](https://pubmed.ncbi.nlm.nih.gov/39413799/)
7. [Proteome-wide mapping and reverse vaccinology-based B and T cell multi-epitope subunit vaccine designing for immune response reinforcement against Porphyromonas gingivalis.](https://pubmed.ncbi.nlm.nih.gov/32928063/)
8. [The UniProt website API: facilitating programmatic access to protein knowledge.](https://pubmed.ncbi.nlm.nih.gov/40331428/)
9. [Identifier mapping performance for integrating transcriptomics and proteomics experimental results.](https://pubmed.ncbi.nlm.nih.gov/21619611/)