Common URL API
The NCBI-BLAST Common URL API allows you to run searches remotely. It supports the same
commands at the NCBI web server and at a cloud provider installation. This allows you to switch from
running searches at the NCBI web server to a cloud provider (or visa versa) with minimal effort.
Every call to the Common URL API must include the CMD
parameter, which can take one of four different
arguments. You may use Put
for search submission, Get
for checking the
status of a submission or retrieving results, Delete
to remove a search and
its results or DisplayRIDs
to list all RIDs in the system. Each argument to
CMD
requires or allows certain other parameters as described in the table below.
The table below lists all supported parameters. Other parameters are not supported and should not be
relied upon by users of the URL API. An asterisk (*) in the CMD
column indicates that the parameter is
required for that command.
Also, see the information at Running Web BLAST and authentication.
Parameter | Definition | Type | CMD | Allowed values |
---|---|---|---|---|
QUERY |
Search query | String | Put * | Accession, GI, or FASTA. |
DATABASE |
BLAST database | String | Put * | Database from appendix 2 or one uploaded to blastdb_custom (see appendix 4) |
PROGRAM |
BLAST program | String | Put * | One of blastn, blastp, blastx, tblastn, tblastx. To enable megablast, use PROGRAM=blastn&MEGABLAST=on . |
FILTER |
Low complexity filtering | String | Put | F to disable. T or L to enable. Prepend “m” for mask at lookup (e.g., mL) |
FORMAT_TYPE |
Report type | String | Put, Get | HTML, Text, XML, XML2, JSON2, or Tabular. HTML is the default. |
EXPECT |
Expect value | Double | Put | Number greater than zero. |
NUCL_REWARD |
Reward for matching bases (BLASTN and megaBLAST) | Integer | Put | Integer greater than zero. |
NUCL_PENALTY |
Cost for mismatched bases (BLASTN and megaBLAST) | Integer | Put | Integer less than zero. |
GAPCOSTS |
Gap existence and extension costs | String | Put | Pair of positive integers separated by a space such as “11 1”. |
MATRIX |
Scoring matrix name | String | Put | One of BLOSUM45, BLOSUM50, BLOSUM62, BLOSUM80, BLOSUM90, PAM250, PAM30 or PAM70. Default: BLOSUM62 for all applicable programs |
HITLIST_SIZE |
Number of databases sequences to keep | Integer | Put,Get | Integer greater than zero. |
DESCRIPTIONS |
Number of descriptions to print (applies to HTML and Text) | Integer | Put,Get | Integer greater than zero. |
ALIGNMENTS |
Number of alignments to print (applies to HTML and Text) | Integer | Put,Get | Integer greater than zero. |
NCBI_GI |
Show NCBI GIs in report | String | Put, Get | T or F |
RID |
BLAST search request identifier | String | Get *, Delete * | The Request ID (RID) returned when the search was submitted |
THRESHOLD |
Neighboring score for initial words | Integer | Put | Positive integer (BLASTP default is 11). Does not apply to BLASTN or MegaBLAST). |
WORD_SIZE |
Size of word for initial matches | Integer | Put | Positive integer. |
COMPOSITION_BASED_STATISTICS |
Composition based statistics algorithm to use | Integer | Put | One of 0, 1, 2, or 3. See comp_based_stats command line option in the BLAST+ user manual for details. |
FORMAT_OBJECT |
Object type | String | Get | SearchInfo (status check) or Alignment (report formatting). |
NUM_THREADS |
Number of virtual CPUs to use | Integer | Put | Integer greater than zero and less than the maximum number of cores on the instance (default is the maximum number of cores on the instance). Supported only on the cloud |
If a parameter is not required and not provided, then the default value will be used. That default value may depend upon the BLAST search you are running.