Common URL API

Common URL API¶

The NCBI-BLAST Common URL API allows you to submit BLAST searches and retrieve BLAST results programmatically.

Every call to the Common URL API must include the CMD parameter, which can take one of two different arguments. You may use Put for search submission, or Get for checking the status of a submission or retrieving results after its completion. Each argument to CMD requires or allows certain other parameters as described in the table below. The table below lists all supported parameters. Parameters not listed are not supported and should not be relied upon by users of this API.

An asterisk (*) after the parameter indicates that the parameter is required for that command.

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.

Parameters to submit the search¶

Parameter	Definition	Type	Allowed values	Default value	Applicable for
CMD *	Operation to perform	String	`Put`	None	All programs
QUERY *	Search query	String	Accession, GI, or FASTA	None	All programs
DATABASE *	BLAST database	String	Database file name (e.g.: `core_nt`, `swissprot`)	None	All programs
PROGRAM *	BLAST program	String	One of `blastn`, `blastp`, `blastx`, `tblastn`, `tblastx`. To enable megablast, use `PROGRAM=blastn&MEGABLAST=on`.	blastn	None
FILTER	Low complexity filtering	String	`F` to disable. `T` or `L` to enable. Prepend “m” for mask at lookup (e.g., `mL`)	blastn: `mL` blastp,tblastn,blastx:`F`, tblastx: `L`	All programs
EXPECT	Expect value	Double	Number greater than zero (e.g.: `10`, `1e-3`)	10	All programs
NUCL_REWARD NUCL_PENALTY	Reward for matching bases Penalty for mismatched bases	Positive integer Negative integer	Combination of reward,penalty parameters. `1,-2`, `1,-3`, `2,-3`, `1,-4`, `4,-5`, `1,-1`	blastn: `2,-3` megablast: `1,-2`	blastn, megablast
WORD_SIZE	Size of word for initial matches	Integer	blastn: `7`, `11`, `15` megablast: `16`, `20`, `24`, `28`, `32`, `48`, `64` blastp: `3`, `5`, `6` tblastn, blastx: `2`, `3`, `5`, `6` tblastx: `2`, `3`	blastn: `11` megablast: `28` blastp, tblastx: `3` tblastn,blastx:`5`	All programs
GAPCOSTS	Gap existence and extension costs	String	Pair of positive integers separated by a space. blastn: `4 4`, `2 4`, `0 4`, `3 3`, `6 2`, `5 2`, `4 2`, `2 2` blastp,blastx,tblastn: `11 2`, `10 2`, `9 2`, `8 2`, `7 2`, `6 2`, `13 1`, `12 1`, `11 1`, `10 1`, `9 1`	blastn: `5 2` blastp,blastx,tblastn: `11 2`	blastn, blastp , blastx, tblastn
MATRIX	Scoring matrix name	String	`BLOSUM45`, `BLOSUM50`, `BLOSUM62`, `BLOSUM80`, `BLOSUM90`, `PAM250`, `PAM30` or `PAM70`.	BLOSUM62	blastp , blastx, tblastn, tblastx
COMPOSITION_BASED_STATISTICS	Composition based statistics algorithm to use	Integer	`0`, `1`, `2`, or `3`. See `comp_based_stats` command line option in the BLAST+ user manual.	2	blastp , blastx, tblastn, tblastx
HITLIST_SIZE	Number of databases sequences to keep	Integer	Integer greater than zero.	100	All programs
SHORT_QUERY_ADJUST	Automatically adjust parameters for input sequences shorter than 30 bases/residues	String	`true` or `false`	false	blastn, blastp
FORMAT_TYPE	Report type	String	`HTML`, `Text`, `XML2`, `XML2_S`, `JSONSA`, `JSON2`, `JSON2_S`, `SAM`.	HTML	All programs
DESCRIPTIONS	Number of descriptions to print	Integer	Integer greater than zero.	100	All programs, HTML, Text formats
ALIGNMENTS	Number of alignments to print	Integer	Integer greater than zero.	100	All programs, HTML, Text formats
NCBI_GI	Show NCBI GIs in report	String	`true` or `false`	false	blastn, tblastn, tblastx
NO_DATABASE_OVERRIDE Experimental: this parameter is subject to removal without notice	Do not automatically switch nt to core_nt	String	`true` or `false`	false	blastn, tblastn, tblastx

Parameters to retrieve results¶

Parameter	Definition	Type	Allowed values	Default value	Applicable for
CMD *	Operation to perform	String	`Get`	None	All programs
RID *	BLAST search request identifier	String	The Request ID (RID) returned when the search was submitted	None	All programs
FORMAT_TYPE	Report type	String	`HTML`, `Text`, `XML2`, `XML2_S`, `JSONSA`, `JSON2`, `JSON2_S`, `SAM`. For tabular `Text` output use `FORMAT_TYPE=Text&ALIGNMENT_VIEW=Tabular`. For tabular `CSV` output use `FORMAT_TYPE=CSV&ALIGNMENT_VIEW=Tabular`.	HTML	All programs
DESCRIPTIONS	Number of descriptions to print	Integer	Integer greater than zero.	100	All programs, HTML,Text formats
ALIGNMENTS	Number of alignments to print	Integer	Integer greater than zero.	100	All programs, HTML,Text formats
NCBI_GI	Show NCBI GIs in report	String	`true` or `false`	false	blastn, tblastn, tblastx