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_P33810.xml
http://www.uniprot.org/uniref/UniRef90_P33810.rdf
http://www.uniprot.org/uniref/UniRef90_P33810.fasta
http://www.uniprot.org/uniref/UniRef90_P33810.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

There is an option to have data from referenced data sets included directly in the returned data, if there is any available:

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).

Batch Retrieval of Entries

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

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 $agent = LWP::UserAgent->new;
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, e.g. all reviewed human entries:

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

You may then retrieve either the set of entries in one of the supported download formats, or a simple list of entry identifiers, which could be stored and later used to detect changes, or the result table itself.

Tips: Explore the various download options of each data set. Get familiar with the query builder by using the Fields link next to the query form. Use the Customize display to select the columns for retrieving result tables in tab delimited or Excel format.

The web address for a query result consists of a data set name (e.g. uniprot, uniref, uniparc, taxonomy, ...) and the actual query. The following 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)

Mapping Identifiers

To use the database 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 $agent = LWP::UserAgent->new;
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";

## 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

import java.util.logging.Logger;

public class ToolExample
{
  private static final String base = "http://www.uniprot.org";
  private static final Logger log = Logger.getAnonymousLogger();
  
  private static void run(String tool, NameValuePair[] params)
    throws Exception
  {
    HttpClient client = new HttpClient();
    String location = base + '/' + tool + '/';
    HttpMethod method = new PostMethod(location);
    ((PostMethod) method).addParameters(params);
    method.setFollowRedirects(false);
    log.info("Submitting...");
    int status = client.executeMethod(method);
    
    if (status == HttpStatus.SC_MOVED_TEMPORARILY)
    {
      location = method.getResponseHeader("Location").getValue();
      method.releaseConnection();
      method = new GetMethod(location);
      status = client.executeMethod(method);
    }
    
    while (true)
    {
      int wait = 0;
      Header header = method.getResponseHeader("Retry-After");
      if (header != null)
        wait = Integer.valueOf(header.getValue());
      if (wait == 0)
        break;
      log.info("Waiting (" + wait + ")...");
      Thread.sleep(wait * 1000);
      method.releaseConnection();
      method = new GetMethod(location);
      status = client.executeMethod(method);
    }
    
    if (status == HttpStatus.SC_OK)
      System.out.println(method.getResponseBodyAsString());
    else
      log.severe("Failed, got " + method.getStatusLine() + " for " + method.getURI());
    
    method.releaseConnection();
  }
  
  public static void main(String[] args)
    throws Exception
  {
    run("mapping", new NameValuePair[] {
      new NameValuePair("from", "ACC"),
      new NameValuePair("to", "P_REFSEQ_AC"),
      new NameValuePair("format", "tab"),
      new NameValuePair("query", "P13368 P20806 Q9UM73 P97793 Q17192"),
    });
    
  }
}

Format Conversion

This service allows you to convert data between different formats.

Example, using the Jakarta Commons HttpClient library:

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();
int status = client.executeMethod(method);
if (status != HttpStatus.SC_OK)
  println(method.getStatusLine());
else println(method.getResponseBodyAsString());

Note that at the moment only single entries are supported.