NCBI Bookshelf. A service of the National Library of Medicine, National Institutes of Health.

BLAST® Help [Internet]. Bethesda (MD): National Center for Biotechnology Information (US); 2008-.

Cover of BLAST® Help

BLAST® Help [Internet].

Show details

SOAP-based BLAST Web Service

and .

Author Information

Created: ; Last Update: July 15, 2011.

Overview

The Simple Object Access Protocol (SOAP)-based BLAST Web Service offers software developers the possibility to develop applications that access the BLAST resources at NCBI in their programming language of choice, relying on widely adopted industry standards such as XML (Extensible Markup Language) and WSDL (Web Service Definition Language).

The service definition can be found in http://www.ncbi.nlm.nih.gov/blast/netblast/blastws.cgi?WSDL and the underlying data structures use the NCBI data model in its XML schema representation. This service provides a simple interface for submitting and retrieving BLAST results that does not require deep knowledge of the NCBI data model as well as a more complete interface which does require knowledge of the NCBI data model and the BLAST 4 network protocol, and familiarity with Abstract Syntax Notation (ASN.1) (see references). The simple (“Lite”) interface allows developers to quickly build a tool around this service, but should provide sufficient flexibility for most projects.

The usage model of the service is simple. The user submits a search, receives a BLAST Request ID (RID), and then uses the RID to check the status of the search, retrieve results, or a search strategy (see below). The BLAST web pages at blast.ncbi.nlm.nih.gov will also accept the RID. For scripted retrieval at the BLAST web page please follow the syntax documented by the QBLAST URL API or use the blast_formatter BLAST+ command line application.

This document’s intended audience is software developers and it requires working knowledge of web services frameworks using SOAP and WSDL.

Usage policy

Please see guidelines under “Web service interface” in http://blast.ncbi.nlm.nih.gov/Blast.cgi?CMD=Web&PAGE_TYPE=BlastDocs&DOC_TYPE=DeveloperInfo

Interface description

BLAST search submission: SubmitSearch

This function accepts a Blast4-queue-search-request structure as input. Please note that the program and service fields should be populated with the values returned via the GetSupportedPrograms function. Similarly to Blast4-queue-search-request-lite, this data structure contains fields for the query, subject (a generalization of a BLAST database), and options and it returns a string containing a BLAST RID.

The Blast4-queries type allows the specification of sequence data in its Bioseq-set field, sequence identifiers as a list of Seq-loc objects, and Position Specific Scoring Matrix (PSSM) in its PssmWithParameters field.

The Blast4-subject type allows the specification of sequence data as a list of Bioseq objects or a BLAST database name as a string (the available BLAST databases can be obtained using the GetDatabases function).

The options to BLAST can be specified either using the paramset field (the supported values can be obtained using the GetSupportedTasks function) or any of the Blast4-parameters objects. This data type is a list of Blast4-parameter objects, which are essentially key-value pairs. The names of the options supported in the algorithm-options field and their data types can be obtained using the GetSupportedOptions function, and these options are documented in the C++ CBlastOptions class reference. The program-options field only supports the “EntrezQuery” name with a string value which represents the Entrez query to use to restrict the BLAST database search.

Checking BLAST search status: CheckSearchStatus

This function takes as input a Blast4-get-search-status-request, whose only field is an RID and returns a Blast4-get-search-status-reply which contains a string indicating whether the search corresponding to that RID is 'ready', 'pending', or whether an 'error' occurred.

Getting BLAST search results: GetSearchResults

This function takes as input a Blast4-get-search-results-request, which requires an RID and returns a Blast4-get-search-results-reply. The latter type contains results applicable to the search originally submitted. The simplified BLAST results (Blast4-simple-results) can be obtained by including the Blast4-result-types::simple-results bitmask in the optional result-types field of the Blast4-get-search-results-request. The simplified results include target sequence identifiers, start and stop of the alignments, number of identities and number of insertions and deletions. The data provided is similar to that in the BLAST tabular report.

Please note that in order to format the BLAST results one can use the RID on the BLAST web pages, in the blast_formatter BLAST+ command line application, or using the QBLAST URL API.

Getting a BLAST search’s search strategy: GetSearchStrategy

This function takes as input a Blast4-get-search-strategy-request, whose only field is an RID and returns a Blast4-get-search-strategy-reply, which is an alias for the Blast4-queue-search-request type. This is the canonical way of storing search strategies and can be utilized in the BLAST web pages as well as the BLAST+ command line applications.

Retrieving a list of available BLAST databases: GetDatabases

This takes a Blast4-request structure, whose body field contains a Blast4-request-body with a get-databases element. The ident field of the Blast4-request is an identifier for the client. This function returns a Blast4-get-databases-reply, which is a list of Blast4-database-info structures containing database specific information.

Retrieving a list of supported scoring matrices: GetSupportedMatrices

This takes a Blast4-request structure, whose body field contains a Blast4-request-body with a get-matrices element. The ident field of the Blast4-request is an identifier for the client. This function returns a Blast4-get-matrices-reply, which is a list of Blast4-matrix-id structures.

Retrieving a list of supported BLAST algorithm options: GetSupportedOptions

This takes a Blast4-request structure, whose body field contains a Blast4-request-body with a get-parameters element. The ident field of the Blast4-request is an identifier for the client. This function returns a Blast4-get-parameters-reply, which is a list of Blast4-parameter-info structures containing the names and data types of the algorithm options to BLAST. These tasks are documented in the BLAST+ user manual.

Retrieving a list of supported common BLAST tasks: GetSupportedTasks

This takes a Blast4-request structure, whose body field contains a Blast4-request-body with a get-paramsets element. The ident field of the Blast4-request is an identifier for the client. This function returns a Blast4-get-paramsets-reply, which is a list of Blast4-task-info structures containing the names and documentation for the tasks supported by the BLAST service. Please note that the concepts of 'task' and 'paramset' are synonymous.

Retrieving a list of supported BLAST programs: GetSupportedPrograms

This takes a Blast4-request structure, whose body field contains a Blast4-request-body with a get-programs element. The ident field of the Blast4-request is an identifier for the client. This function returns a Blast4-get-programs-reply, which is a list of Blast4-program-info structures containing programs and services available for each program.

Retrieving sequence data: GetSequences

This takes a Blast4-request structure, whose body field contains a Blast4-request-body with a Blast4-get-sequences-request element. This specifies the source BLAST database and the sequence identifiers for the sequences requested. The ident field of the Blast4-request is an identifier for the client. This function returns a Blast4-get-sequences-reply, which is a list of Bioseq objects.

Sample code and support

This interface has been tested using the NCBI C++ SOAP API, the Apache Axis2 Web Service framework, the Microsoft .NET Framework version 3.5, and the SOAP::Lite Perl module. Sample clients for each of these frameworks can be found in the BLAST Web Services FTP site (see references).

For feedback, questions, bug reports, and support, please contact blast-help@ncbi.nlm.nih.gov.

Copyright Notice. BLAST is a registered Trademark of the National Library of Medicine.
Bookshelf ID: NBK55699
PubReader format: click here to try

Views

Other titles in this collection

Contact us

Recent Activity

Your browsing activity is empty.

Activity recording is turned off.

Turn recording back on

See more...