POP-OUT | CLOSE

RCSB PDB - SOAP Web Services:


Documentation

Software developers can now write tools to communicate with the RCSB PDB resources using the SOAP framework  .


RCSB PDB Web Services JAVA API

The RCSB PDB Web Services description language file (WSDL) is available at: http://www.rcsb.org/pdb/services/pdbws?wsdl. The methods provided by the SOAP API are documented here (JavaDoc  ).

JavaDoc  
org.pdb.ws.general

Interface PdbWebService

All Superinterfaces:
Remote 
public interface PdbWebService
extends Remote

The Interface for the RCSB PDB WebService. A number of different functions are provided. The most important one is the runXmlQuery(java.lang.String), which allows to run any of the RCSB advanced queries via SOAP.

Method Summary
 String blastPDB (String sequence, double eCutOff, String matrix, String outputFormat)
          BLASTs the given sequence against the sequences in the RCSB PDB and returns the output.
 String blastPDB (String structureId, String chainId, double eCutOff, String matrix, String outputFormat)
          BLASTs the sequence of the given chain against the sequences in the RCSB PDB and returns the output
 String blastQueryXml (String sequence, double eCutOff)
          BLASTs the given sequence against the sequences in the RCSB PDB and returns the output as XML
 String blastStructureIdQueryXml (String structureId, String chainId, double eCutOff)
          BLASTs the sequence of the given chain against the sequences in the RCSB PDB and returns the output as XML
 String[] fastaQuery(String sequence, double eCutOff)
          Runs FASTa against the given sequence and returns an array of matching PDB IDs
 String[] fastaStructureIdQuery (String structureId, String chainId, double eCutOff)
          Runs FASTa against the sequence of the given chain and returns an array of matching PDB IDs
 Atom_siteWS getAtomSite (String structureId)
          Returns the first atom site object for a structure.
 Atom_siteWS[] getAtomSites(String structureId)
          Returns the atom site objects for a structure.
 int getChainLength(String structureId, String chainId)
          Finds the length of the given chain.
 String[] getChains(String structureId)
          Finds all the chain identifiers for a given structure.
 String getCifChain(String structureId, String chainId)
          Converts author-assigned chain identifiers into their corrected (mmCIF) equivalents.
 int getCifChainLength(String structureId, String chainId)
           
 String[] getCifChains(String structureId)
          Finds all the mmCIF chain identifiers for a given structure.
 int getCifResidue(String structureId, String chainId, String residueId)
          Converts an author-assigned residue identifier into its corrected (mmCIF) equivalent.
 String[] getCurrentPdbIds()
          Finds all the PDB Identifiers (aka PDB IDs) that are "current" structures - not obsolete, models, etc.
 String[] getDbRefIds(String in0, String in1, String in2)
           
 String getDisorder(String in0, String in1)
           
 DomainFragmentWS[] getDomainFragments(String structureId, String chainId, String method)
          Find all structural protein domain fragments for a given structureId
 String[] getEcNums()
          Finds all the Enzyme Classification numbers associated with all PDB strucutures
 String[] getEcNumsForStructures(String[] structureIds)
          Finds all the Enzyme Classification numbers associated with the given PDB strucutures.
 int[] getEntities(String structureId)
          Finds the mmCIF entity IDs for a given structure
 String[] getGenomeDetails()
          Finds genome details for all PDB structures
 String getIdStatus(String structureId)
          Finds the status of the given structure - one of CURRENT, OBSOLETE, UNRELEASED, MODEL, or UNKNOWN
 String getKabschSander(String structureId, String chainId)
          Finds secondary structure for the given chain
 String[] getObsoletePdbIds()
          Gets the list of obsolete PDB ids
 String getPdbChain(String in0, String in1)
          Finds the length of the given chain, where the chain identifier is the mmCIF version.
 String getPrimaryCitationTitle(String structureId)
          For structures with a primary citation, will find the title of the citation
 String[] getPubmedIdForAllStructures()
          Finds all the Pubmed IDs associated with PDB structures
 String getPubmedIdForStructure(String structureId)
          Finds a Pubmed ID for the given structure.
 String[] getReleaseDates(String[] structureIds)
          Finds the release dates for the given structures
 String getSequenceForStructureAndChain(String structureId, String chainId)
          Finds the sequence for the given chain
 SnpInfo[] getSnpInfo(String structureId)
          Get SnpInfo for a PDB id
 String[] getSnps()
          Return all PDBs that have SNPs in the database.
 String getSpaceGroupForStructure(String structureId)
          Finds the symmetry.space_group_name_H_M field for a structure (see mmCIF dictionary for more info)
 String[] getStructureGenomicsPdbIds()
          Finds info for structural genomics structures
 String[] getSwissProtIds()
          Returns the mapping from PDB and chain ID to UniProtKB entries.
 int isStructureIdObsolete(String structureId)
          Determines if the given structure is obsolete
 String[] keywordQuery(String keywordExpression, boolean exactMatch, boolean restrictToAuthors)
          Runs a keyword query, like what would happen if you entered a search phrase in the search box at the top of the RCSB PDB web site.
 String[] pubmedAbstractQuery(String keywordExpression)
          Runs a keyword query, like what would happen if you entered a search phrase in the search box on the Pubmed Abstract page (e.g., http://www.pdb.org/pdb/explore/pubmed.do?structureId=4HHB)
 String[] runXmlQuery(String xmlQuery)
          This is the most important web service call provided by RCSB-PDB, since it allows to access all of the advanced search functionality via a web service.

Method Detail

runXmlQuery


String[] runXmlQuery(String xmlQuery)
                     throws RemoteException
This is the most important web service call provided by RCSB-PDB, since it allows to access all of the advanced search functionality via a web service. Runs any RCSB advanced query. This works by posting the XML representation of an advanced query. The XML representation of a query can be found by pressing the show query details link on the left hand menu. To generate a query XML, use the RCSB PDB web site to build a query, then choose the "Show Query Details" link in the left-hand navigation menu.

See also the RESTful web service documentation: /pdb/rest.

Parameters:
xmlQuery - The XML representing a RCSB advanced query.
Returns:
An array of PDB IDs
Throws:
RemoteException

blastPDB


String blastPDB(String sequence,
                double eCutOff,
                String matrix,
                String outputFormat)
                throws RemoteException
BLASTs the given sequence against the sequences in the RCSB PDB and returns the output
Parameters:
sequence - A protein sequence
eCutOff - See BLAST documentation for details
matrix - See BLAST documentation for details
outputFormat - See BLAST documentation for details
Returns:
The output of the BLAST program
Throws:
RemoteException

blastPDB


String blastPDB(String structureId,
                String chainId,
                double eCutOff,
                String matrix,
                String outputFormat)
                throws RemoteException
BLASTs the sequence of the given chain against the sequences in the RCSB PDB and returns the output
Parameters:
structureId - A PDB Structure Identifier (aka PDB ID)
chainId - An author-assigned Chain Identifier
eCutOff - See BLAST documentation for details
matrix - See BLAST documentation for details
outputFormat - See BLAST documentation for details
Returns:
The output of the BLAST program
Throws:
RemoteException

blastQueryXml


String blastQueryXml(String sequence,
                     double eCutOff)
                     throws RemoteException
BLASTs the given sequence against the sequences in the RCSB PDB and returns the output as XML
Parameters:
sequence - A protein sequence
eCutOff - See BLAST documentation for details
Returns:
The output of the BLAST program as XML
Throws:
RemoteException

blastStructureIdQueryXml


String blastStructureIdQueryXml(String structureId,
                                String chainId,
                                double eCutOff)
                                throws RemoteException
BLASTs the sequence of the given chain against the sequences in the RCSB PDB and returns the output as XML
Parameters:
structureId - A PDB Structure Identifier (aka PDB ID)
chainId - An author-assigned Chain Identifier
eCutOff - See BLAST documentation for details
Returns:
The output of the BLAST program as XML
Throws:
RemoteException

fastaQuery


String[] fastaQuery(String sequence,
                    double eCutOff)
                    throws RemoteException
Runs FASTa against the given sequence and returns an array of matching PDB IDs
Parameters:
sequence - A protein sequence
eCutOff - See FASTa documentation for details
Returns:
An array of matching PDB Structure Identifiers (aka PDB IDs)
Throws:
RemoteException

fastaStructureIdQuery


String[] fastaStructureIdQuery(String structureId,
                               String chainId,
                               double eCutOff)
                               throws RemoteException
Runs FASTa against the sequence of the given chain and returns an array of matching PDB IDs
Parameters:
structureId - A PDB Structure Identifier (aka PDB ID)
chainId - An author-assigned Chain Identifier
eCutOff - See FASTa documentation for details
Returns:
An array of matching PDB Structure Identifiers (aka PDB IDs)
Throws:
RemoteException

getAtomSite


Atom_siteWS getAtomSite(String structureId)
                        throws RemoteException
Returns the first atom site object for a structure. Not really useful except for testing.
Parameters:
structureId - A PDB Structure Identifier (aka PDB ID)
Returns:
An atom site object. Probably not the optimal representation of an atom site - it has 86 fields!
Throws:
RemoteException

getAtomSites


Atom_siteWS[] getAtomSites(String structureId)
                           throws RemoteException
Returns the atom site objects for a structure.
Parameters:
structureId - A PDB Structure Identifier (aka PDB ID)
Returns:
An array of atom site objects. Probably not the optimal representation of an atom site - it has 86 fields!
Throws:
RemoteException

getChainLength


int getChainLength(String structureId,
                   String chainId)
                   throws RemoteException
Finds the length of the given chain.
Parameters:
structureId - A PDB Structure Identifier (aka PDB ID)
chainId - An author-assigned Chain Identifier
Returns:
The length of the given chain
Throws:
RemoteException

getChains


String[] getChains(String structureId)
                   throws RemoteException
Finds all the chain identifiers for a given structure.
Parameters:
structureId - A PDB Structure Identifier (aka PDB ID)
Returns:
The author-assigned chain identifiers for the given structure
Throws:
RemoteException

getCifChain


String getCifChain(String structureId,
                   String chainId)
                   throws RemoteException
Converts author-assigned chain identifiers into their corrected (mmCIF) equivalents.
Parameters:
structureId - A PDB Structure Identifier (aka PDB ID)
chainId - An Author-Assigned Chain Identifier
Returns:
The chain identifier (mmCIF) of the given chain
Throws:
RemoteException

getPdbChain


String getPdbChain(String in0,
                   String in1)
                   throws RemoteException
Finds the length of the given chain, where the chain identifier is the mmCIF version.
Parameters:
structureId - A PDB Structure Identifier (aka PDB ID)
chainId - An mmCIF Chain Identifier
Returns:
The length of the given chain
Throws:
RemoteException

getCifChainLength


int getCifChainLength(String structureId,
                      String chainId)
                      throws RemoteException
Throws:
RemoteException

getCifChains


String[] getCifChains(String structureId)
                      throws RemoteException
Finds all the mmCIF chain identifiers for a given structure.
Parameters:
structureId - A PDB Structure Identifier (aka PDB ID)
Returns:
The mmCIF chain identifiers for the given structure. Note that these are NOT the author-assigned identifiers, although often they can match. For an example, check out the mmCIF file for 1AEW.
Throws:
RemoteException

getCifResidue


int getCifResidue(String structureId,
                  String chainId,
                  String residueId)
                  throws RemoteException
Converts an author-assigned residue identifier into its corrected (mmCIF) equivalent.
Parameters:
structureId - A PDB Structure Identifier (aka PDB ID)
chainId - An author-assigned Chain Identifier
residueId - An author-assigned Residue Identifier including insertion code (if present)
Returns:
Throws:
RemoteException

getCurrentPdbIds


String[] getCurrentPdbIds()
                          throws RemoteException
Finds all the PDB Identifiers (aka PDB IDs) that are "current" structures - not obsolete, models, etc.
Returns:
An array of current PDB IDs
Throws:
RemoteException

getDomainFragments

DomainFragmentWS[] getDomainFragments(String structureId,
                                      String chainId,
                                      String method)
                                      throws RemoteException
Find all structural protein domain fragments for a given structureId
Parameters:
structureId - A PDB Structure Identifier (aka PDB ID)
chainId - An author-assigned Chain Identifier (may be null if domain fragments of all chains are required)
method - A domain prediction method (one of 'SCOP', 'CATH', 'dp' and 'pdp' -- may be null if all are required)
Returns:
an array of DomainFramgentWS objects.
Throws:
RemoteException - if the supplied PDB id is null, or if there was an internal server error

getEcNums

String[] getEcNums()
                   throws RemoteException
Finds all the Enzyme Classification numbers associated with all PDB strucutures
Returns:
An array of strings, where each string contains the PDB ID, the author-assigned chain ID, and the EC number, separated by tabs.
Throws:
RemoteException

getEcNumsForStructures

String[] getEcNumsForStructures(String[] structureIds)
                                throws RemoteException
Finds all the Enzyme Classification numbers associated with the given PDB strucutures.
Parameters:
structureIds - An array of PDB IDs
Returns:
An array of strings, where each string contains the PDB ID, the author-assigned chain ID, and the EC number, separated by tabs.
Throws:
RemoteException

getEntities

int[] getEntities(String structureId)
                  throws RemoteException
Finds the mmCIF entity IDs for a given structure
Parameters:
structureId - A PDB Structure Identifier (aka PDB ID)
Returns:
an array of entity IDs
Throws:
RemoteException

getGenomeDetails

String[] getGenomeDetails()
                          throws RemoteException
Finds genome details for all PDB structures
Returns:
An array of strings, where each string contains the PDB ID, the author-assigned chain ID, the locus ID, and the OMIM number, separated by tabs.
Throws:
RemoteException

getIdStatus

String getIdStatus(String structureId)
                   throws RemoteException
Finds the status of the given structure - one of CURRENT, OBSOLETE, UNRELEASED, MODEL, or UNKNOWN
Parameters:
structureId - A PDB Structure Identifier (aka PDB ID)
Returns:
one of CURRENT, OBSOLETE, UNRELEASED, MODEL, or UNKNOWN
Throws:
RemoteException

getKabschSander

String getKabschSander(String structureId,
                       String chainId)
                       throws RemoteException
Finds secondary structure for the given chain
Parameters:
structureId - A PDB Structure Identifier (aka PDB ID)
chainId - An author-assigned Chain Identifier
Returns:
the Kabsch-Sander secondary structure string
Throws:
RemoteException

getDisorder

String getDisorder(String in0,
                   String in1)
                   throws RemoteException
Throws:
RemoteException

getDbRefIds

String[] getDbRefIds(String in0,
                     String in1,
                     String in2)
                     throws RemoteException
Throws:
RemoteException

getObsoletePdbIds

String[] getObsoletePdbIds()
                           throws RemoteException
Gets the list of obsolete PDB ids
Returns:
An array of PDB IDs for all obsolete structures.
Throws:
RemoteException

getPrimaryCitationTitle

String getPrimaryCitationTitle(String structureId)
                               throws RemoteException
For structures with a primary citation, will find the title of the citation
Parameters:
structureId - A PDB Structure Identifier (aka PDB ID)
Returns:
The title of the primary citation
Throws:
RemoteException

getPubmedIdForAllStructures

String[] getPubmedIdForAllStructures()
                                     throws RemoteException
Finds all the Pubmed IDs associated with PDB structures
Returns:
An array of strings, where each string contains the PDB ID and the Pubmed ID, separated by a comma
Throws:
RemoteException

getPubmedIdForStructure

String getPubmedIdForStructure(String structureId)
                               throws RemoteException
Finds a Pubmed ID for the given structure. Not very useful for structures with multiple associated Pubmed IDs.
Parameters:
structureId -
Returns:
A Pubmed ID
Throws:
RemoteException

getReleaseDates

String[] getReleaseDates(String[] structureIds)
                         throws RemoteException
Finds the release dates for the given structures
Parameters:
structureIds - An array of PDB IDs
Returns:
An array of strings, where each string contains the PDB ID and the release date, separated by a tab
Throws:
RemoteException

getSequenceForStructureAndChain

String getSequenceForStructureAndChain(String structureId,
                                       String chainId)
                                       throws RemoteException
Finds the sequence for the given chain
Parameters:
structureId - A PDB Structure Identifier (aka PDB ID)
chainId - An author-assigned Chain Identifier
Returns:
A sequence
Throws:
RemoteException

getSnpInfo

SnpInfo[] getSnpInfo(String structureId)
                     throws RemoteException
Get SnpInfo for a PDB id
Parameters:
structureId -
Returns:
Throws:
RemoteException

getSnps

String[] getSnps()
                 throws RemoteException
Return all PDBs that have SNPs in the database. (coming from LS-SNP)
Returns:
Throws:
RemoteException

getSpaceGroupForStructure

String getSpaceGroupForStructure(String structureId)
                                 throws RemoteException
Finds the symmetry.space_group_name_H_M field for a structure (see mmCIF dictionary for more info)
Parameters:
structureId - A PDB Structure Identifier (aka PDB ID)
Returns:
A space group (see mmCIF dictionary for more info)
Throws:
RemoteException

getStructureGenomicsPdbIds

String[] getStructureGenomicsPdbIds()
                                    throws RemoteException
Finds info for structural genomics structures
Returns:
An array of strings where each string contains the target_id, database_name, and database_id separated by tabs.
Throws:
RemoteException

getSwissProtIds

String[] getSwissProtIds()
                         throws RemoteException
Returns the mapping from PDB and chain ID to UniProtKB entries.
Returns:
the mapping from PDB and chain ID to UniProtKB codes.
Throws:
RemoteException

isStructureIdObsolete

int isStructureIdObsolete(String structureId)
                          throws RemoteException
Determines if the given structure is obsolete
Parameters:
structureId - A PDB Structure Identifier (aka PDB ID)
Returns:
1 if obsolete, 0 if not
Throws:
RemoteException

keywordQuery

String[] keywordQuery(String keywordExpression,
                      boolean exactMatch,
                      boolean restrictToAuthors)
                      throws RemoteException
Runs a keyword query, like what would happen if you entered a search phrase in the search box at the top of the RCSB PDB web site.
Parameters:
keywordExpression - A search phrase - uses lucene syntax
exactMatch - determines if lucene should do an exact word match or not
restrictToAuthors - if true then only the author fields will be searched
Returns:
An array of PDB IDs
Throws:
RemoteException

pubmedAbstractQuery

String[] pubmedAbstractQuery(String keywordExpression)
                             throws RemoteException
Runs a keyword query, like what would happen if you entered a search phrase in the search box on the Pubmed Abstract page (e.g., http://www.pdb.org/pdb/explore/pubmed.do?structureId=4HHB)
Parameters:
keywordExpression - A search phrase - uses lucene syntax
Returns:
An array of PDB IDs
Throws:
RemoteException

Web service client examples

An introduction how to write Web Service clients using the RCSB PDB SOAP services is available here (Java).


JAVA - SOAP web services

Use the Axis framework to generate the web service client code using the following command line:

java org.apache.axis.wsdl.WSDL2Java "http://www.rcsb.org/pdb/services/pdbws?wsdl"

For a more detailed introduction into how to develop web services using the RCSB soap interface see the developing web services page.

Then you can run e.g. the code below to execute a BLAST search against PDB:

import java.io.PrintStream; import java.net.URL; import org.pdb.webservices.PdbWebService; import org.pdb.webservices.PdbWebServiceServiceLocator; public class BlastPDB { public static void main(String[] _args) { // call the blast method below using this sequence and the ecutoff value blastThePDB("VLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHGKKVADALTNAVAHVDDMPL", 10); } private static void blastThePDB(String _sequence, double _eCutOff) { // build the service locator object. This object was created by Axis wsdl2java PdbWebServiceServiceLocator locator = new PdbWebServiceServiceLocator(); try { // construct my URL object String _url = "http://www.pdb.org/pdb/services/pdbws"; URL url = new URL(_url); // Get the web services interface (axis-generated interface) PdbWebService p = locator.getpdbws(url); // print some feedback to the standard out System.out.println("Blasting... "); // call the blast program on the PDB server using these parameters String output = p.blastPDB(_sequence, _eCutOff, "BLOSUM62" , "HTML"); // print the output System.out.println ( "output : " + output ); // save the output into f file File outputFile = new File ("MyBlastResults.html"); PrintStream printer = new PrintStream ( outputFile ); printer.print(output); printer.flush(); printer.close(); System.out.println("Blast is complete"); } catch (Exception _e) { _e.printStackTrace(); } } }
 
PERL - SOAP web services

The following is an client that performs a Blast search on the PDB database.

#!/usr/bin/perl use SOAP::Lite; #The next three variables need to have datatypes defined explicitly $sequence = SOAP::Data->type(string =>'VLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHGKKVADALTAVAHVDDMPNAL'); $scoreMatrix = SOAP::Data->type(string =>'BLOSUM62'); $outputFormat = SOAP::Data->type(string =>'HTML'); #Get an instance of the SOAP Service to the PDB WSDL my $service = SOAP::Lite -> uri('http://www.pdb.org/pdb/services/pdbws') -> proxy('http://www.pdb.org/pdb/services/pdbws'); # Another type-safe input parameter my $eCutOffValue = SOAP::Data->type(double => 10.0); # Make the blast call my $result = $service->blastPDB( $sequence, $eCutOffValue, $scoreMatrix, $outputFormat); # Check to see if there is an error unless ($result->fault) { print $result->result(); } else { print join ', ', $result->faultcode, $result->faultstring; } #Print the result print "here is the result: \n$result";
 
Python - SOAP web services

Example: Blast the PDB using a protein sequence

  1. Install the SOAPpy library
  2. Install the fconst library

For Python web services development and library download see: http://pywebsvcs.sourceforge.net/

The following is a python script that allows you to run blast on the PDB server and return HTML results.

#!/usr/bin/env python import SOAPpy server = SOAPpy.SOAPProxy("http://www.pdb.org/pdb/services/pdbws") blastOutput = server.blastPDB ( "VLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHGKKVADALTNAVAHVDDMPNAL", 10.0, "BLOSUM62", "HTML" ); print blastOutput
 
C/C++ - SOAP web services

Example of C code using the gSOAP toolkit: http://sourceforge.net/projects/gsoap2

#include "stdio.h" #include "soapH.h" #include "pdbFileSoapBinding.nsmap" int main() { struct soap soap; soap_init(&soap); char* sequence = "SPMKSEYLGDAGVIDSCSDWPNTPPDNNFNGGFAPDQPQLVTPIISDIPIDLNQIYVPTPPQLLDNCSIIYYELDTPIGETFKVSAR"; double eCutoff = 10.0; char* matrix = "BLOSUM62"; // outputs are can also be formated as specified by the BLAST documentation // for example the line below can be "-m 8" for tabular output or "XML" for xml output char* outputFormat = "HTML"; char* output; printf ( "Blasting the following sequence... "); printf ( sequence ); // MAKE THE SERVER CALL! if ( soap_call_ns1__blastPDB ( &soap, NULL, NULL, sequence, eCutoff, matrix, outputFormat, &output ) == SOAP_OK ){ // PRINT THE OUTPUT printf ( output ); } else { soap_print_fault(&soap, stderr); } soap_destroy(&soap); soap_end(&soap); soap_done(&soap); return 0; }
 

RESTful

Documentation is available for RCSB PDB RESTful Web Services.