The UniProt website API: facilitating programmatic access to protein knowledge

1The ongoing worldwide proliferation of biological data has spurred the need for advanced data organization and accessibility portals for users. Researchers are presented with the challenge of integrating large amounts of complex data from diverse databases and formats to advance their research and contextualize their findings. Having free access to resources that collect, organize, and effectively present data from bioinformatics databases has become increasingly vital for scientific communities. This access helps to power research pipelines, provide context for new discoveries, and increase the overall impact of scientific findings.

2The Universal Protein Resource (UniProt) is a comprehensive suite of databases providing the scientific community with freely accessible, high-quality protein sequence and function information. This includes molecular functions, biological processes, cellular localization, molecular interactions, and disease-associated variations, along with detailed positional features such as active sites, binding sites, disulfide bonds, regions, and domains. UniProt integrates metadata from 180 cross-referenced databases spanning genomics, proteomics, protein function, and variation data, establishing a network of interconnected data resources and their experimental datasets. This integration enables researchers to conduct analyses across diverse biological data sources. In the UniProt Knowledgebase (UniProtKB), protein sequences are assigned stable identifiers and are enriched by manual and automatic annotation processes, summarizing protein functions and experimental evidence. The UniProt Reference Clusters (UniRef) database provides protein sequence clustering at various levels of sequence identity and the UniProt Archive (UniParc) maintains a complete, non-redundant repository of known protein sequences, including database cross-references and a comprehensive change history.

3Here, we present the UniProt website API, which supports UniProt.org and provides programmatic access to protein knowledge across the UniProt databases. We provide an overview of the available data, outline the API’s architecture, demonstrate how to search and retrieve information, showcase illustrative examples, and conclude with a description of the help documentation.

4The website REST API provides access to all UniProt databases and tools through dedicated services, summarized in Table 1. Further details are available in the UniProt API documentation (https://www.uniprot.org/api-documentation), which is also discussed later in this paper. Each data service operates independently, providing access to its respective database. However, these services can be connected through shared data types and identifiers, enabling users to query and integrate data across multiple databases.

5UniProtKB primary accessions serve as the central unifying keys. With a UniProtKB primary accession, users can retrieve detailed annotations and cross-references from UniProtKB, retrieve archived sequence versions in UniParc, explore sequence similarity clusters in UniRef, and identify the associated proteomes. Finally, the supporting data databases are utilized throughout UniProt, enhancing the consistency and depth of protein information available. The UniProt databases have been extensively detailed in a previous publication. To facilitate seamless data integration, the ID Mapping service (https://www.uniprot.org/api-documentation/idmapping) allows users to map database identifiers (UniProt or cross-referenced) to another database. This enables users to establish links between biological databases for their protein of interest and enrich their result datasets with UniProtKB entry information.

6With the ever-growing size and complexity of biological data, it is essential for the underlying architecture to scale effectively while ensuring fast and efficient data retrieval to meet the needs of our users. To meet these challenges, our system is built with a modular design that incorporates several key components: API Gateway, service layer, search engine, and key-value store.

7The API Gateway (Fig. 1a) is the entry point for all user requests (programmatic clients, web browsers, or bots) and routes them to the appropriate service, such as UniProtKB, UniRef, or UniParc (Fig. 1b). The number of instances for each service can be auto-scaled depending on user demand. These services are implemented in Java using Spring Boot (spring.io/projects/spring-boot).

8Each service within the UniProt website API interacts with two distributed systems: Solr (Fig. 1c) (solr.apache.org) for search operations and Voldemort (Fig. 1d) (github.com/voldemort/voldemort) for data retrieval. The use of distributed systems enhances scalability, performance, and fault tolerance, ensuring that the API can efficiently handle large-scale queries and data requests. To maintain system reliability, we manage our Solr clusters using ZooKeeper (zookeeper.apache.org), which coordinates servers and manages configuration settings.

9Solr processes user queries through its high-performance search engine, returning matching IDs. These IDs serve as references to retrieve complete UniProt entries from Voldemort, which stores the full annotated data, including biological information, functional annotations, and cross-references. Voldemort is designed for low-latency access and supports horizontal scaling with in-memory caching to further optimize performance. To reduce retrieval times, all data in Voldemort are compressed using the Brotli algorithm (github.com/google/brotli), reducing the size of stored and transmitted data by 14% and lowering the latency by 20% when compared with typical gzip compression.

10The UniProt website API allows RESTful access to the various UniProt databases. Each database has three common types of endpoints: entry, search, and stream (see Table 2). They support multiple response formats, including tabular forms like TSV or Excel, or more complex structures like JSON, XML, RDF, or FASTA format (see https://www.uniprot.org/api-documentation). This variety of popular formats allows for easier integration into diverse user workflows without requiring additional transformation on the user’s side.

11The entry endpoint retrieves a specific entry using its unique identifier. The search endpoint returns a paginated list of entries matching a given query, which can be either a plain text search or an advanced query with specific fields. Pagination is crucial for efficiently displaying results, preventing the system from loading millions of entries at once. The stream endpoint accepts the same input as the search endpoint but returns all results in a single response, enabling large-scale retrieval. However, this approach has the trade-off that the request cannot be resumed if the connection is lost.

12As mentioned earlier, the search endpoint is a paginated API. It returns a page of results and a “Link” response header to fetch the next page if it exists. By default the page size is 25, which can be changed by passing the request query parameter “size” with a maximum page size of 500. In contrast, the stream API downloads all the results at once with a limit of 10 million on the result size either in compressed or uncompressed formats.

13There are common query parameters in each endpoint. For example, there is the “fields” parameter to request a list of comma-separated values in the response (e.g. fields = accession,organism_name,gene_names). For tabular formats such as TSV, fields are returned in the requested order, enabling granular customization of the response and simplifying downstream usage in a user workflow.

14The search and stream endpoints have a common query parameter called “query” across the different databases. The “query” parameter is used to pass the search criteria, e.g. “query = protein_name:rubisco.” The search criteria can be either free text or a valid Solr query with logical operators AND, OR, and NOT. For the search endpoints, the “sort” parameter allows the user to sort the result on a certain field or list of fields [e.g. query = “((gene:CTNNB1) AND (taxonomy_id:9606))” and sort = organism_name asc].

15In each of the endpoints, we have included additional HTTP response headers that users might be interested in, such as total number of query hits (X-Total-Results), open next page of results (Link), release version (X-UniProt-Release), and release date (X-UniProt-Release-Date).

16In addition to the common endpoints, we have light endpoints for UniParc and UniRef to get the core data of an entry. UniRef has the /members endpoint to obtain cluster members for a given cluster ID. We also provide two additional endpoints in UniParc to retrieve cross-references by UniParc ID: /uniparc/{upi}/databases for paginated results and /uniparc/{upi}/databases/stream for downloading all cross-references. All of our endpoints have validations and error handling with appropriate HTTP status codes (see Supplementary Table S1).

17The underlying data for the UniProt website are updated every 8 weeks, with the code updated more frequently with new features and improvements. The website API is not linked to the data release, which makes it quicker to release fixes and improvements. We announce upcoming major changes one release in advance, allowing users to prepare accordingly; all previous changes are documented in the release notes (https://www.uniprot.org/release-notes?query=*).

18The ID Mapping service is an asynchronous job API service to map the identifiers of one database to another, e.g. RefSeq IDs to UniProtKB IDs. ID Mapping has four main API endpoints that allow the user to submit a job, obtain the status, and download the results (see Table 3).

19Users are able to download the mapped ID results with UniProt data if the target mapping is to UniProtKB, UniRef, or UniParc entries. In the case of mapping from UniProt IDs to third-party databases, the user will receive only the database ID, allowing them to use these other database APIs or services to retrieve further data not directly related to UniProt.

20Similar to other endpoints, users are able to obtain either paginated results that can be queried and sorted or all results at once through the last two endpoints in Table 3. Please refer to the UniProt REST tutorial (https://www.uniprot.org/help/uniprot_rest_tutorial) for an example user case. A user may submit multiple ID Mapping jobs; however, a single job request is limited to a maximum of 100 000 IDs. Job results are stored on the server for a maximum of 7 days, after which jobs will need to be resubmitted.

21For detailed programmatic methodology of both example use cases, please see the Supplementary data. Results and methodology are correct as of release 2025_01.

22The Website API provides an intuitive and versatile way for users to access the knowledge stored in the UniProt datasets and integrate it into their own analysis pipelines. To showcase the ability of the website API to search across UniProt datasets, we reference the sequence archive UniParc which provides links to UniProtKB, a rich, interconnected database of protein function and feature annotation. Additionally, as an example of how to use data from cross-referenced databases to search UniProt datasets, we will be using a nasal swab sequence stored in the European Nucleotide Archive (ENA) of which we assume the user does not have prior knowledge of the proteins’ identity.

23The user is provided with a sequence of a SARS-CoV-2 isolate (which was sequenced from a nasal swab in Washington in March 2020) and wishes to use it to understand the mechanism of SARS-CoV-2 transmission to wild white-tailed deer during the global pandemic.

24The sequence was originally submitted to ENA with a unique identifier QIZ14413 (https://www.ebi.ac.uk/ena/browser/view/QIZ14413). A search within UniProtKB for this identifier returns no results (https://www.uniprot.org/uniprotkb?query=QIZ14413). As UniParc (www.uniprot.org/help/uniparc) is a database of protein sequences sourced from public sequence databases, including ENA, it can be searched via source database identifiers (such as QIZ14413 (https://www.uniprot.org/uniparc?query=QIZ14413)) which will return the unique protein sequence stored with a stable unique identifier, in this case UniParc ID UPI00131F240A (https://www.uniprot.org/uniparc/UPI00131F240A/entry). Within this entry’s cross-references, we see P0DTC2 (https://www.uniprot.org/uniprotkb/P0DTC2/entry), which is a reviewed UniProtKB entry specifically for SARS-CoV-2 spike glycoprotein containing a wealth of protein function and feature annotations (https://www.uniprot.org/uniprotkb).

25Spike glycoprotein (P0DTC2) is a structural protein of SARS-CoV-2 that mediates virus entry into the host cell. To determine which host protein spike glycoproteins bind to, manually curated interaction data can be identified by extracting subunit structure data from the P0DTC2 entry (https://www.uniprot.org/uniprotkb/P0DTC2/entry#interaction). This returns evidence from publications that indicate interactions with human angiotensin-converting enzyme 2 (hereafter referred to as ACE2) and a search of UniProtKB for reviewed entries with the gene name ACE2 in human finds the entry Q9BYF1 (https://www.uniprot.org/uniprotkb/Q9BYF1/entry).

26Querying for “regions” in ACE2 sequence features identifies three distinct regions that are annotated as binding to SARS-CoV spike glycoprotein: regions between the residue numbers 30–41, 82–84, and 353–357 (https://www.uniprot.org/uniprotkb/Q9BYF1/entry#family_and_domains). Examining the mutagen features at these residue ranges confirms there is experimental evidence for SARS-CoV-2 spike glycoprotein interaction at these sites, suggesting that these regions could be fundamental in the interaction with both SARS-CoV and SARS-CoV-2 spike glycoproteins (https://www.uniprot.org/uniprotkb/Q9BYF1/entry#disease_variants).

27To determine whether these regions of interaction between human ACE2 and spike glycoproteins are conserved in white-tailed deer (TaxID: 9874), a search for the ACE2 gene in white-tailed deer in UniProtKB returns the entry A0A6J0Z472 (https://www.uniprot.org/uniprotkb/A0A6J0Z472/entry). Alignment of A0A6J0Z472 and Q9BYF1 using the EBI’s Clustal Omega Multiple Sequence Alignment service (https://europepmc.org/article/MED/38597606) indicates reasonable evolutionary conservation between these species. Focusing on the spike glycoprotein interaction regions indicated in human ACE2 indicates that all three of these regions are highly conserved in white-tailed deer. This suggests that the infection initiation mechanism in humans of spike glycoprotein binding to host ACE2 is also likely to be the mechanism by which SARS-CoV-2 is able to infect white-tailed deer.

28The ID Mapping service (https://www.uniprot.org/id-mapping) allows users to map identifiers from one database to another database. This is a vital feature when using multiple source databases or processing software as part of a larger integrated analysis pipeline. Conversion of gene names to database identifiers is commonly used to facilitate further analysis and understanding of a results dataset. In this example, gene names are entered as the input and UniProtKB/Swiss-Prot IDs as the output with a taxonomy restriction (e.g. human TaxID: 9606) to restrict the results to species-specific identifiers. Results identify a one-to-one identifier mapping. Additionally, users can download the protein entry information from the output UniProtKB entries.

29We provide REST API documentation through Swagger (https://www.uniprot.org/api-documentation), which follows the OpenAPI specification 3.x. Swagger enables users to explore API endpoints, test API calls interactively, and generate request snippets in various languages, including Bash (cURL), Python, JavaScript, Perl, and R. Users can navigate through different tabs to find the appropriate API for their dataset.

30We provide a React-based web interface (https://www.uniprot.org/) for searching and visualizing dataset entries. As a thin client, it relies on our REST API to dynamically populate the page. The web interface groups search results by various attributes, making filtering easier and helping with the exploration of the API capabilities by exposing them through the User Interface (UI). It can also generate REST API URLs based on user queries that can then be shared with other users. Additionally, users can download search results in supported formats. Beyond search functionality, the web interface serves as a valuable resource for biological knowledge, help documentation, upcoming changes, and online training advertisements.

31The primary goal of our REST APIs is to provide platform-independent access to comprehensive, high-quality protein-related data available in the UniProt databases. Users can query and retrieve data in multiple formats, enabling the scientific community to access information according to their specific research needs. Our extensive Swagger documentation details the full range of data attributes and access methods, with practical examples provided across multiple programming languages. The APIs are designed for seamless integration, allowing researchers to automate data retrieval, conduct large-scale analyses, and efficiently incorporate UniProt data into their workflows. Our APIs are free to use and do not require login or authentication, ensuring open and easy access for all users.