How can I access resources on this web site programmatically?

Retrieving individual entries

The web address for an entry consists of a data set name (e.g. uniprot, uniref, uniparc, taxonomy, ...) and the entry's unique identifier, e.g.:

http://www.uniprot.org/uniprot/P12345

By default, a web page is returned. Depending on the data set, other formats may also be available (check the orange buttons 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:

http://www.uniprot.org/uniprot/P12345.rdf?include=yes

The following status codes may be returned:

Resolving RDF identifiers

A request for an address such as

http://purl.uniprot.org/uniprot/P12345

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 'application/rdf+xml'.

Batch retrieval of entries

Entries can be retrieved in batch by querying our batch retrieval service with a list of UniProt identifers. Here is a Perl example.

use strict;
use warnings;
use LWP::UserAgent;

my $list = $ARGV[0]; # File containg list of UniProt identifiers.

my $base = 'http://www.uniprot.org';
my $tool = 'batch';

my $contact = ''; # Please set your email address here to help us debug in case of problems.
my $agent = LWP::UserAgent->new(agent => "libwww-perl $contact");
push @{$agent->requests_redirectable}, 'POST';

my $response = $agent->post("$base/$tool/",
                            [ 'file' => [$list],
                              'format' => 'txt',
                            ],
                            'Content_Type' => 'form-data');

while (my $wait = $response->header('Retry-After')) {
  print STDERR "Waiting ($wait)...\n";
  sleep $wait;
  $response = $agent->get($response->base);
}

$response->is_success ?
  print $response->content :
  die 'Failed, got ' . $response->status_line .
    ' for ' . $response->request->uri . "\n";

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:

http://www.uniprot.org/uniprot/?query=reviewed:yes+AND+organism:9606

Click the orange 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 of the Search tab by clicking Advanced Search ». Click Customize 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 (e.g. uniprot, uniref, uniparc, taxonomy, ...) and the actual query. The following query parameters are supported:

The following example retrieves all human entries matching the term 'antigen' in RDF/XML and tab-delimited format, respectively.

http://www.uniprot.org/uniprot/?query=organism:9606+AND+antigen&format=rdf&compress=yes

http://www.uniprot.org/uniprot/?query=organism:9606+AND+antigen&format=tab&compress=yes&columns=id,reviewed,protein names

The next example retrieves all human entries with cross-references to PDB in tab-delimited format, showing only the UniProtKB and PDB identifiers.

http://www.uniprot.org/uniprot/?query=organism:9606+AND+database:pdb&format=tab&compress=yes&columns=id,database(PDB)

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 lwp-mirror or curl with the -z option. Here are examples of how to do this in Perl:

• Download all UniProt sequences for a given organism in FASTA format

  use strict;
  use warnings;
  use LWP::UserAgent;
  use HTTP::Date;
  
  my $taxon = $ARGV[0]; # Taxonomy identifier of organism.
  
  my $query = "http://www.uniprot.org/uniprot/?query=organism:$taxon&format=fasta&include=yes";
  my $file = $taxon . '.fasta';
  
  my $contact = ''; # Please set your email address here to help us debug in case of problems.
  my $agent = LWP::UserAgent->new(agent => "libwww-perl $contact");
  my $response = $agent->mirror($query, $file);
  
  if ($response->is_success) {
    my $results = $response->header('X-Total-Results');
    my $release = $response->header('X-UniProt-Release');
    my $date = sprintf("%4d-%02d-%02d", HTTP::Date::parse_date($response->header('Last-Modified')));
    print "Downloaded $results entries of UniProt release $release ($date) to file $file\n";
  }
  elsif ($response->code == HTTP::Status::RC_NOT_MODIFIED) {
    print "Data for taxon $taxon is up-to-date.\n";
  }
  else {
    die 'Failed, got ' . $response->status_line .
      ' for ' . $response->request->uri . "\n";
  }
  

• Download the UniProt complete or reference proteomes for all organisms below a given taxonomic node in FASTA format

  use strict;
  use warnings;
  use LWP::UserAgent;
  use HTTP::Date;
  
  # Taxonomy identifier of top node for query, e.g. 2 for Bacteria, 2157 for Archea, etc.
  # (see http://www.uniprot.org/taxonomy)
  my $top_node = $ARGV[0];
  
  my $reference = 0; # Toggle this to 1 if you want reference instead of complete proteomes.
  my $proteome = $reference ? 'reference:yes' : 'complete:yes';
  my $keyword = $reference ? 'keyword:1185' : 'keyword:181';
  
  my $contact = ''; # Please set your email address here to help us debug in case of problems.
  my $agent = LWP::UserAgent->new(agent => "libwww-perl $contact");
  
  # Get a list of all taxons below the top node with a complete/reference proteome.
  my $query_list = "http://www.uniprot.org/taxonomy/?query=ancestor:$top_node+$proteome&format=list";
  my $response_list = $agent->get($query_list);
  die 'Failed, got ' . $response_list->status_line .
    ' for ' . $response_list->request->uri . "\n"
    unless $response_list->is_success;
  
  # For each taxon, mirror its proteome in FASTA format.
  for my $taxon (split(/\n/, $response_list->content)) {
    my $file = $taxon . '.fasta';
    my $query_taxon = "http://www.uniprot.org/uniprot/?query=organism:$taxon+$keyword&format=fasta&include=yes";
    my $response_taxon = $agent->mirror($query_taxon, $file);
  
    if ($response_taxon->is_success) {
      my $results = $response_taxon->header('X-Total-Results');
      my $release = $response_taxon->header('X-UniProt-Release');
      my $date = sprintf("%4d-%02d-%02d", HTTP::Date::parse_date($response_taxon->header('Last-Modified')));
      print "File $file: downloaded $results entries of UniProt release $release ($date)\n";
    }
    elsif ($response_taxon->code == HTTP::Status::RC_NOT_MODIFIED) {
      print "File $file: up-to-date\n";
    }
    else {
      die 'Failed, got ' . $response_taxon->status_line .
        ' for ' . $response_taxon->request->uri . "\n";
    }
  }
  

Release number and date

If you would like to record the UniProt release number and/or date of the data which you retrieve, you can extract this information from the HTTP header of the response (see this Perl example):

use strict;
use warnings;
use LWP::UserAgent;

my $query = $ARGV[0]; # Query URL.

my $contact = ''; # Please set your email address here to help us debug in case of problems.
my $agent = LWP::UserAgent->new(agent => "libwww-perl $contact");
my $response = $agent->get($query);

if ($response->is_success) {
  print 'UniProt release ' . $response->header('X-UniProt-Release') .
  ' of ' . $response->header('Last-Modified') . "\n";
}
else {
  die 'Failed, got ' . $response->status_line .
    ' for ' . $response->request->uri . "\n";
}

• X-UniProt-Release: contains the UniProt release number, e.g. 2010_08
• Last-Modified: contains the UniProt release date, e.g. Tue, 13 Jul 2010 00:00:00 GMT

Format conversion

This service allows you to convert data between different formats. Note that at the moment only single entries are supported. Here is a Java example (using the Jakarta Commons HttpClient library) to convert a UniProtKB entry from txt to rdf format.

PostMethod method = new PostMethod("http://www.uniprot.org/convert");
Part[] parts =
{
  new StringPart("type", "uniprot"),
  new StringPart("from", "txt"),
  new StringPart("to", "rdf"),
  new FilePart("data", new File("P05067.txt"))
};
method.setRequestEntity(new MultipartRequestEntity(parts, method.getParams()));
HttpClient client = new HttpClient();
String contact = ""; // Please set your email address here to help us debug in case of problems.
client.setRequestHeader("User-Agent", "Java " + contact);
int status = client.executeMethod(method);
if (status != HttpStatus.SC_OK)
  println(method.getStatusLine());
else
  println(method.getResponseBodyAsString());

Mapping database identifiers

To use our database identifier 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:

use strict;
use warnings;
use LWP::UserAgent;

my $base = 'http://www.uniprot.org';
my $tool = 'mapping';

my $params = {
  from => 'ACC',
  to => 'P_REFSEQ_AC',
  format => 'tab',
  query => 'P13368 P20806 Q9UM73 P97793 Q17192'
};

my $contact = ''; # Please set your email address here to help us debug in case of problems.
my $agent = LWP::UserAgent->new(agent => "libwww-perl $contact");
push @{$agent->requests_redirectable}, 'POST';

my $response = $agent->post("$base/$tool/", $params);

while (my $wait = $response->header('Retry-After')) {
  print STDERR "Waiting ($wait)...\n";
  sleep $wait;
  $response = $agent->get($response->base);
}

$response->is_success ?
  print $response->content :
  die 'Failed, got ' . $response->status_line .
    ' for ' . $response->request->uri . "\n";

import urllib,urllib2

url = 'http://www.uniprot.org/mapping/'

params = {
'from':'ACC',
'to':'P_REFSEQ_AC',
'format':'tab',
'query':'P13368 P20806 Q9UM73 P97793 Q17192'
}

data = urllib.urlencode(params)
request = urllib2.Request(url, data)
contact = "" # Please set your email address here to help us debug in case of problems.
request.add_header('User-Agent', 'Python %s' % contact)
response = urllib2.urlopen(request)
page = response.read(200000)

## tool_example.rb ##
require 'net/http'

base = 'www.uniprot.org'
tool = 'mapping'
params = {
  'from' => 'ACC', 'to' => 'P_REFSEQ_AC', 'format' => 'tab',
  'query' => 'P13368 P20806 Q9UM73 P97793 Q17192'
}

http = Net::HTTP.new base
$stderr.puts "Submitting...\n";
response = http.request_post '/' + tool + '/',
  params.keys.map {|key| key + '=' + params[key]}.join('&')

loc = nil
while response.code == '302'
  loc = response['Location']
  response = http.request_get loc
end

while loc
  wait = response['Retry-After'] or break
  $stderr.puts "Waiting (#{wait})...\n";
  sleep wait.to_i
  response = http.request_get loc
end

response.value # raises http error if not 2xx
puts response.body

package example;

import java.io.InputStream;
import java.io.UnsupportedEncodingException;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLConnection;
import java.net.URLEncoder;
import java.util.logging.Logger;

public class Example
{
  private static final String UNIPROT_SERVER = "http://www.uniprot.org/";
  private static final Logger LOG = Logger.getAnonymousLogger();

  private static void run(String tool, ParameterNameValue[] params)
    throws Exception
  {
    StringBuilder locationBuilder = new StringBuilder(UNIPROT_SERVER + tool + "/?");
    for (int i = 0; i < params.length; i++)
    {
      if (i > 0)
        locationBuilder.append('&');
      locationBuilder.append(params[i].name).append('=').append(params[i].value);
    }
    String location = locationBuilder.toString();
    URL url = new URL(location);
    LOG.info("Submitting...");
    HttpURLConnection conn = (HttpURLConnection) url.openConnection();
    HttpURLConnection.setFollowRedirects(true);
    conn.setDoInput(true);
    conn.connect();

    int status = conn.getResponseCode();
    while (true)
    {
      int wait = 0;
      String header = conn.getHeaderField("Retry-After");
      if (header != null)
        wait = Integer.valueOf(header);
      if (wait == 0)
        break;
      LOG.info("Waiting (" + wait + ")...");
      conn.disconnect();
      Thread.sleep(wait * 1000);
      conn = (HttpURLConnection) new URL(location).openConnection();
      conn.setDoInput(true);
      conn.connect();
      status = conn.getResponseCode();
    }
    if (status == HttpURLConnection.HTTP_OK)
    {
      LOG.info("Got a OK reply");
      InputStream reader = conn.getInputStream();
      URLConnection.guessContentTypeFromStream(reader);
      StringBuilder builder = new StringBuilder();
      int a = 0;
      while ((a = reader.read()) != -1)
      {
        builder.append((char) a);
      }
      System.out.println(builder.toString());
    }
    else
      LOG.severe("Failed, got " + conn.getResponseMessage() + " for "
        + location);
    conn.disconnect();
  }

  public static void main(String[] args)
    throws Exception
  {
    run("mapping", new ParameterNameValue[] {
      new ParameterNameValue("from", "ACC"),
      new ParameterNameValue("to", "P_REFSEQ_AC"),
      new ParameterNameValue("format", "tab"),
      new ParameterNameValue("query", "P13368 P20806 Q9UM73 P97793 Q17192"),
    });
  }

  private static class ParameterNameValue
  {
    private final String name;
    private final String value;

    public ParameterNameValue(String name, String value)
      throws UnsupportedEncodingException
    {
      this.name = URLEncoder.encode(name, "UTF-8");
      this.value = URLEncoder.encode(value, "UTF-8");
    }
  }
}