- UniProt, the Universal Protein Resource, is one of the most important biological databases for protein sequence and functional information. It provides access to protein sequences, gene associations, molecular functions, biological processes, subcellular locations, protein domains, post-translational modifications, disease associations, molecular interactions, and links to other biological resources. Researchers use UniProt in genomics, proteomics, molecular biology, evolutionary studies, functional annotation, and comparative analysis. The UniProt REST API enables users to access this information programmatically, making it possible to search, retrieve, download, and integrate protein data through automated bioinformatics workflows.
- A REST API, or Representational State Transfer Application Programming Interface, allows software applications to communicate with a web service using standard HTTP requests. The UniProt REST API provides access to UniProt databases through web addresses and request parameters. Instead of manually searching the UniProt website and downloading individual records, researchers can use programming languages such as Python and R, command-line tools, or web browsers to retrieve the required information automatically. The API supports multiple data formats and provides services for individual record retrieval, database searching, large-scale downloads, and identifier mapping.
- The main API service is available through the base address https://rest.uniprot.org/. Different endpoints provide access to specific UniProt resources and functions. The major resources include UniProtKB, UniParc, UniRef, Proteomes, and the identifier mapping service. UniProtKB provides protein knowledge records, UniParc maintains sequence records and their histories, UniRef groups similar protein sequences into clusters, and Proteomes provides information about the protein content of organisms and biological samples. The ID Mapping service connects identifiers from UniProt and other biological databases.
- UniProtKB, or UniProt Knowledgebase, is the central resource for protein sequence and functional annotation. It contains two major sections: Swiss-Prot and TrEMBL. Swiss-Prot contains manually reviewed and curated protein records, while TrEMBL contains computationally annotated records that have not undergone the same level of manual review. Reviewed records generally provide more carefully evaluated functional information, but the level of experimental evidence varies between individual annotations. TrEMBL is particularly valuable because it provides extensive protein coverage, including proteins from organisms for which detailed manual annotation may not yet be available.
- The REST API provides three major methods for retrieving information from UniProtKB and other supported databases: entry retrieval, search, and streaming. Entry retrieval is used when the accession number of a particular record is already known. Search retrieves records matching a specified query and returns results in manageable pages. Streaming retrieves a large matching result set through a single streamed response. These methods support different retrieval requirements and allow users to select an appropriate strategy according to the size and purpose of their analysis.
- The entry endpoint retrieves an individual record using its accession number. For UniProtKB, the general structure is https://rest.uniprot.org/uniprotkb/{accession}. For example, the following request retrieves a UniProtKB record in JSON format:
- https://rest.uniprot.org/uniprotkb/P05067.json
- The accession in this example identifies a specific UniProtKB protein record. The response contains structured information about the protein, including its accession, recommended name, organism, sequence, functional annotations, and cross-references where available. Other supported formats can be requested by using the appropriate file extension or format parameter. Common formats include JSON, XML, text, FASTA, and tabular representations. The choice of format depends on whether the researcher needs a complete annotated record, a protein sequence, or selected fields for statistical analysis.
- Entry retrieval is particularly useful when a researcher has a known UniProt accession and wants to obtain its protein sequence or annotation. For example, a protein accession obtained from a publication, genome annotation project, or another biological database can be used to retrieve its corresponding UniProtKB record. Researchers can also use entry retrieval to examine the functional description, organism, sequence length, protein family, subcellular location, and available experimental evidence. For large lists of accessions, however, identifier mapping or batch-oriented retrieval methods may be more efficient than sending many individual requests.
- The search endpoint retrieves records that satisfy a specified query. Its general structure is https://rest.uniprot.org/uniprotkb/search?query={search_query}. The query can contain a protein name, gene symbol, organism identifier, functional annotation, accession-related information, or combinations of field-specific conditions. For example, the following request searches for human proteins associated with the gene symbol TP53:
- https://rest.uniprot.org/uniprotkb/search?query=gene:TP53%20AND%20organism_id:9606
- The search expression combines the gene field with the NCBI taxonomy identifier for humans. The API returns matching records according to the query and available annotations. Using organism identifiers is often more precise than relying only on common or scientific names, particularly when a gene symbol occurs in multiple species.
- UniProt supports a specialized query syntax that allows users to search particular fields. For example, gene:TP53 searches using a gene name, organism_id:9606 restricts results to human records, and reviewed:true selects reviewed UniProtKB entries. Other fields can be used to search protein names, sequence length, functional annotations, subcellular locations, enzyme classifications, and database cross-references. Query expressions can be combined using Boolean operators such as AND, OR, and NOT. For example, gene:TP53 AND organism_id:9606 AND reviewed:true searches for reviewed human records associated with TP53. Exact field names and supported query expressions should be checked in the current UniProt documentation.
- Search queries can also be restricted by protein properties and biological annotations. Researchers may search for proteins with a particular Gene Ontology term, enzyme classification, conserved domain, or cross-reference to another database. They may also filter results according to sequence length, organism, annotation status, or other available attributes. These advanced searches are useful when investigating protein families, identifying enzymes with particular activities, retrieving proteins associated with a biological process, or selecting reviewed proteins for comparative analysis. The availability of each field depends on the database and its annotation content.
- The search endpoint uses pagination to return large result sets in manageable portions. Rather than transferring every matching record in one response, the API returns a page of results and provides information for retrieving subsequent pages. The default page size is generally 25 records, and the size parameter can increase the page size up to a maximum of 500. The response includes a Link HTTP header when another page is available. Software should follow the supplied next-page link rather than constructing pagination URLs manually, because the API controls the continuation information. Pagination is useful when downloading large datasets incrementally and when processing records without loading the entire result set into memory.
- The stream endpoint is designed for retrieving a large result set through one streamed request. Its general structure is https://rest.uniprot.org/uniprotkb/stream?query={search_query}. It supports query conditions and output-format selection similar to the search endpoint. For example, the following request retrieves matching human TP53 protein sequences in FASTA format:
- https://rest.uniprot.org/uniprotkb/stream?query=gene:TP53%20AND%20organism_id:9606&format=fasta
- Streaming is useful for bulk retrieval because it avoids the need to write a loop that follows individual result pages. However, a streamed download cannot be resumed from the point of interruption in the same way as a paginated retrieval. If the connection fails, the request may need to be restarted. UniProt’s documented stream service supports large result sets, with a stated maximum of up to ten million results for a single request. For extremely large or interruption-prone downloads, paginated retrieval or appropriate bulk-download resources may be preferable.
- The API supports several output formats that serve different analytical purposes. JSON is useful for retrieving structured records and processing them programmatically. XML provides hierarchical data that can be used in systems designed for structured document processing. FASTA is widely used for protein sequence analysis, multiple sequence alignment, phylogenetics, and homology searches. TSV is convenient for tabular data processing and can be imported into spreadsheet software, R, Python, and statistical analysis tools. UniProt also supports other formats, including text and RDF, depending on the endpoint. Selecting the appropriate format reduces the need for additional data conversion and simplifies downstream analysis.
- The ID Mapping service is an important component of the UniProt REST API. Biological databases use different identifier systems, and the same gene or protein may be represented by several identifiers across NCBI, Ensembl, UniProt, RefSeq, and other resources. ID Mapping allows users to convert identifiers from one supported database system to another. For example, a researcher may have RefSeq protein accessions and want to identify their corresponding UniProtKB accessions. Identifier mapping can also connect Ensembl identifiers, gene identifiers, and other supported database references.
- The ID Mapping service operates asynchronously. This means that the user submits a mapping request, receives a job identifier, and then checks the status of the job before retrieving the results. The main endpoints are /idmapping/run for submitting a job, /idmapping/status/{jobId} for checking its status, /idmapping/results/{jobId} for retrieving paginated results, and /idmapping/stream/{jobId} for retrieving all results in a streamed response. The job-based approach is suitable for large identifier lists because the mapping process may take time to complete.
- A simple example of submitting an identifier-mapping request can be implemented using Python:
- import requests
- import time
- base_url = “https://rest.uniprot.org”
- response = requests.post(
- f”{base_url}/idmapping/run”,
- data={
- “from”: “UniProtKB_AC-ID”,
- “to”: “RefSeq_Protein”,
- “ids”: “P05067”
- },
- timeout=30
- )
- response.raise_for_status()
- job_id = response.json()[“jobId”]
- status_url = f”{base_url}/idmapping/status/{job_id}”
- while True:
- status_response = requests.get(status_url, timeout=30)
- status_response.raise_for_status()
- status = status_response.json()
- if status.get(“jobStatus”) == “RUNNING”:
- time.sleep(3)
- continue
- if status.get(“jobStatus”) == “FAILED”:
- raise RuntimeError(“Identifier mapping failed”)
- break
- results_response = requests.get(
- f”{base_url}/idmapping/results/{job_id}”,
- timeout=60
- )
- results_response.raise_for_status()
- print(results_response.json())
- This example demonstrates the general sequence of submitting a mapping job, checking its status, and retrieving the results. The source and target database names must be supported by the current ID Mapping service. For larger lists, identifiers can be supplied in the format required by the API, subject to the documented limit of up to 100,000 identifiers per job. Mapping results are retained for a limited period, documented as up to seven days, so important results should be downloaded and stored promptly. A production workflow should also handle network errors, unexpected response structures, failed jobs, and pagination when the result set is large.
- The UniProt REST API can also be used to retrieve protein information through Python. The requests library provides a straightforward way to send HTTP requests and process responses. For example, the following code retrieves a protein record in JSON format:
- import requests
- accession = “P05067”
- url = f”https://rest.uniprot.org/uniprotkb/{accession}.json”
- response = requests.get(url, timeout=30)
- response.raise_for_status()
- protein_data = response.json()
- print(“Accession:”, protein_data.get(“primaryAccession”))
- print(“Protein name:”,
- protein_data.get(“proteinDescription”))
- print(“Organism:”,
- protein_data.get(“organism”, {}).get(“scientificName”))
- This example illustrates how selected information can be extracted from a returned JSON record. The structure of a UniProtKB response contains nested objects and lists, so more detailed annotation fields may require additional parsing. Researchers should consult the API documentation to identify the exact JSON structure and field locations relevant to their analysis.
- Protein sequences can be retrieved directly in FASTA format. For example:
- import requests
- accession = “P05067”
- url = f”https://rest.uniprot.org/uniprotkb/{accession}.fasta”
- response = requests.get(url, timeout=30)
- response.raise_for_status()
- fasta_sequence = response.text
- print(fasta_sequence)
- The returned FASTA record contains a header describing the protein and its amino acid sequence. The sequence can be saved to a file and used in tools such as BLASTp, Clustal Omega, MUSCLE, MAFFT, or other sequence-analysis programs. When using protein sequences for reproducible analysis, researchers should preserve the accession and version information where available, together with the retrieval date and database release.
- The API can also retrieve selected annotation fields rather than complete records. This is useful when researchers need a table containing only accessions, protein names, gene names, organisms, sequence lengths, or selected functional annotations. The fields parameter can be used with search or stream requests to specify which fields should be returned. For example, a TSV request can be constructed as follows:
- https://rest.uniprot.org/uniprotkb/search?query=organism_id:9606%20AND%20reviewed:true&fields=accession,protein_name,gene_names,organism_name,length&format=tsv
- This query requests selected fields for reviewed human protein records in a tabular format. The exact field identifiers must be supported by the current UniProt API. Researchers should consult the return-fields documentation rather than assuming that display labels from the website are identical to API field names.
- UniProtKB is not the only resource available through the REST API. UniParc, or UniProt Archive, maintains a comprehensive collection of protein sequence records from multiple sources. It is particularly useful for tracking sequence records and their histories, including records that may no longer be present in their original source databases. UniParc focuses on sequence identity and record tracking rather than providing the same level of curated functional annotation as UniProtKB. Researchers can use UniParc to investigate whether a protein sequence has appeared in different databases or under different identifiers.
- UniRef, or UniProt Reference Clusters, groups protein sequences according to sequence similarity and identity thresholds. UniRef100 clusters identical sequences, UniRef90 groups sequences with at least 90% sequence identity under its clustering criteria, and UniRef50 groups more distant sequences using a lower identity threshold. These clusters reduce redundancy and make large-scale sequence analysis more efficient. The REST API allows users to retrieve individual UniRef clusters, search for clusters, and obtain associated sequence and representative information. UniRef is useful for protein family exploration, representative sequence selection, and large-scale similarity analysis.
- Proteomes provides information about the complete or predicted protein content associated with organisms, strains, and other biological samples. Through the API, researchers can retrieve proteome records and use them to investigate protein sets for comparative proteomics, genome annotation, and organism-level functional analysis. Proteome identifiers and their associated metadata can help distinguish different strains, assemblies, and biological datasets. Researchers should check the provenance and completeness of a proteome before treating it as a complete representation of an organism’s proteins.
- The UniProt REST API provides cross-references to many external biological databases. A protein record may contain links to nucleotide sequences, genomic locations, protein structures, conserved domains, pathways, molecular interactions, publications, and disease-related resources. These cross-references allow researchers to combine protein information with data from NCBI, Ensembl, the Protein Data Bank, InterPro, Pfam, Gene Ontology, Reactome, and other resources. Such integration is valuable for functional annotation, protein characterization, systems biology, and multi-omics research.
- The API is especially useful in automated bioinformatics pipelines. A workflow may begin with a list of gene identifiers from a genome analysis, map them to UniProt accessions, retrieve protein sequences, and then perform domain identification or functional annotation. Another workflow may search UniProt for reviewed proteins from a particular organism, download their sequences in FASTA format, and perform comparative analysis. In proteomics, protein accessions identified through mass spectrometry can be used to retrieve functional descriptions, molecular weights, sequence information, and known post-translational modifications. In evolutionary studies, UniProt and UniRef data can support sequence comparisons and the identification of conserved protein families.
- Large-scale API access should be designed carefully. Researchers should use pagination for large search results, select only the fields required for their analysis, and avoid repeatedly requesting identical records. The stream endpoint is useful for large downloads but should be used with awareness of its connection and restart limitations. Identifier mapping jobs should be monitored until completion, and results should be downloaded within the available retention period. Requests should include reasonable timeouts and error handling, and automated workflows should respond appropriately to HTTP status codes such as 400, 404, 429, and 500. A 429 response generally indicates that the service is limiting requests, while server errors may require a later retry.
- The UniProt API is publicly accessible and does not generally require an API key for ordinary data retrieval. Nevertheless, users should follow UniProt’s service guidance, avoid excessive request rates, and use appropriate batching and caching strategies. For extensive or repeated data collection, researchers should consider whether the available bulk-download resources are more suitable than repeated API calls. The API documentation provides the current endpoint specifications, supported parameters, response formats, and service guidance.
- Reproducibility is an important consideration when using the UniProt REST API. Protein records and annotations are updated as new experimental findings, sequence corrections, and computational predictions become available. The same query may therefore return different records or annotations at different times. Researchers should record the exact query expression, endpoint, selected fields, output format, retrieval date, accession numbers, and database release where available. For identifier mapping, the source database, target database, job parameters, and returned mapping results should also be preserved. For sequence analysis, the exact retrieved FASTA records should be archived when possible.
- The UniProt REST API provides an effective connection between protein knowledge and computational biology. Its entry, search, and stream endpoints support individual and large-scale retrieval, while the ID Mapping service connects identifiers across biological databases. Additional resources such as UniParc, UniRef, and Proteomes extend its usefulness to sequence tracking, protein clustering, and organism-level protein analysis. By integrating the API with Python, R, command-line tools, and automated workflows, researchers can retrieve protein sequences and annotations efficiently and use them in functional genomics, proteomics, comparative biology, evolutionary research, and other bioinformatics applications.