How can I access resources on this web site programmatically?
Last modified November 17, 2014
This document describes how this web site can be accessed with programs. All resources (individual entries as well as sets of entries retrieved by queries) are accessible using simple URLs (REST) that can be bookmarked, linked and used in programs.
Please consider to provide your email address as part of the User-Agent header that your programs set. This will allow us to contact you in case of problems.
- Retrieving individual entries
- Batch retrieval of entries (cf. "Retrieve/ID mapping")
- Retrieving entries via queries
- Retrieving a random entry
- Downloading data at every UniProt release
- Release number and date
- Format conversion
- Mapping database identifiers (cf. "Retrieve/ID mapping")
Retrieving individual entries
The web address for an entry consists of a data set name
taxonomy, ...) and the entry's
unique identifier, e.g.:
By default, a web page is returned. Depending on the data set, other formats may also be available (click on "Formats" on the entry's web page). Here are some examples:
http://www.uniprot.org/uniprot/P12345.txt http://www.uniprot.org/uniprot/P12345.xml http://www.uniprot.org/uniprot/P12345.rdf http://www.uniprot.org/uniprot/P12345.fasta http://www.uniprot.org/uniprot/P12345.gff http://www.uniprot.org/uniref/UniRef90_Q76ZR4.xml http://www.uniprot.org/uniref/UniRef90_Q76ZR4.rdf http://www.uniprot.org/uniref/UniRef90_Q76ZR4.fasta http://www.uniprot.org/uniref/UniRef90_Q76ZR4.tab http://www.uniprot.org/uniparc/UPI000000001F.xml http://www.uniprot.org/uniparc/UPI000000001F.rdf http://www.uniprot.org/uniparc/UPI000000001F.fasta http://www.uniprot.org/uniparc/UPI000000001F.tab
For the RDF/XML format there is an option to include data from referenced data sets directly in the returned data:
The following status codes may be returned:
|200||The request was processed successfully.|
|400||Bad request. There is a problem with your input.|
|404||Not found. The resource you requested doesn't exist.|
|410||Gone. The resource you requested was removed.|
|500||Internal server error. Most likely a temporary problem, but if the problem persists please contact us.|
|503||Service not available. The server is being updated, try again later.|
Resolving RDF identifiers
A request for an address such as
will be resolved, where possible, by redirection to the
corresponding resource (see previous section). For UniProt resources,
entries are returned in RDF/XML format if the HTTP
'Accept' request header is set to
Batch retrieval of entries
Retrieving entries via queries
You can use any query to define the set of entries that you are interested in. Best start with an interactive text search to find the base URL for your set, e.g. all reviewed human entries:
or all reviewed entries that were created in the current UniProtKB/Swiss-Prot release:
http://www.uniprot.org/uniprot/?query=reviewed:yes+AND+created:[current TO *]
Click the Download button on the search results page to see the available download formats for your query. Hover your mouse over Download for the format of your choice to see the additional parameters (described in the table below) that you need to append to your base URL to retrieve the entries in this format.
Tips: Explore the various download formats of each data set. Get familiar with the query builder (advanced search form) by clicking on Advanced. Click Columns on the search results page to select the columns for retrieving result tables in tab-delimited or Excel format.
The URL for a query result consists of a data set name
taxonomy, ...) and the actual query.
The following query parameters are supported:
||string||See query syntax and query fields for UniProtKB. An empty query string will retrieve all entries in a data set. Tip: Click Advanced in the search bar.|
Format in which to return results:
||comma-separated list of values, e.g. for UniProtKB:
||Columns to select for retrieving results in
||Include isoform sequences when the
Include description of referenced data when the
This parameter is ignored for all other values of the
Return results gzipped. Note that if the client supports HTTP compression,
results may be compressed transparently even if this parameter is
not set to
||integer||Maximum number of results to retrieve.|
Offset of the first result, typically used together with
The following example retrieves all human entries matching the term '
in RDF/XML and tab-delimited format, respectively.
The next example retrieves all human entries with cross-references to PDB in tab-delimited format, showing only the UniProtKB and PDB identifiers.
Retrieving a random entry
You can retrieve a random entry by appending
&random=yes to any query, e.g. the following query returns a random reviewed human entry:
Downloading data at every UniProt release
The HTTP header
Last-Modified: will avoid that you download data more than once per release,
if you use a download tool that makes use of this information, e.g. the unix commands
curl with the
option. Here are examples of how to do this in Perl:
Release number and date
X-UniProt-Release:contains the UniProt release number, e.g.
Last-Modified:contains the UniProt release date, e.g.
Tue, 13 Jul 2010 00:00:00 GMT
This service allows you to convert data between different
formats. Note that at the moment only single entries are
supported. Here is a
Jakarta Commons HttpClient
library) to convert a UniProtKB entry from
Mapping database identifiers
To use our database identifier mapping ("Retrieve/ID mapping") service programmatically you need to know the abbreviations for the database names. Some databases map only one way.
Here are some examples for querying the database mapping service using:
Related terms: programmatic access, program, script, wget, curl, web services