Ncbi Blast ApiSAFE

🔬 A curated collection of 23,000+ agent skills for empirical research across 8 social science disciplines. | 精选 23,000+ AI Agent 技能库,覆盖8大社会科学学科的实证研究。CoPaper.AI 20分钟完成一篇可复现的规范实证论文,并支持用户上传 Skills。-- Maintained by CoPaper.AI from Stanford REAP.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: ncbi-blast-api
description: "Run sequence similarity searches via the NCBI BLAST REST API"
metadata:
  openclaw:
    emoji: "🧪"
    category: "domains"
    subcategory: "biomedical"
    keywords: ["BLAST", "sequence alignment", "NCBI", "homology search", "protein similarity", "nucleotide search"]
    source: "https://blast.ncbi.nlm.nih.gov/"
---

# NCBI BLAST REST API

## Overview

BLAST (Basic Local Alignment Search Tool) is the most widely used bioinformatics tool, comparing nucleotide or protein sequences against databases to find regions of similarity. The NCBI BLAST REST API enables programmatic submission of searches, status polling, and result retrieval. Free, no authentication required (but rate-limited).

## API Workflow

BLAST searches are asynchronous: submit → poll → retrieve.

### Step 1: Submit Search

```bash
# Nucleotide BLAST (blastn)
curl -X POST "https://blast.ncbi.nlm.nih.gov/blast/Blast.cgi" \
  -d "CMD=Put&PROGRAM=blastn&DATABASE=nt&QUERY=ATGCGATCGATCG..."

# Protein BLAST (blastp)
curl -X POST "https://blast.ncbi.nlm.nih.gov/blast/Blast.cgi" \
  -d "CMD=Put&PROGRAM=blastp&DATABASE=nr&QUERY=MKTLLLTLVVVTIVCL..."

# BLAST with specific parameters
curl -X POST "https://blast.ncbi.nlm.nih.gov/blast/Blast.cgi" \
  -d "CMD=Put&PROGRAM=blastn&DATABASE=nt&QUERY=SEQUENCE&\
EXPECT=0.001&WORD_SIZE=11&HITLIST_SIZE=50"
```

### Step 2: Check Status

```bash
# Poll for completion (returns XML with Status field)
curl "https://blast.ncbi.nlm.nih.gov/blast/Blast.cgi?CMD=Get&FORMAT_OBJECT=SearchInfo&RID=YOUR_RID"
```

### Step 3: Retrieve Results

```bash
# Get results in XML
curl "https://blast.ncbi.nlm.nih.gov/blast/Blast.cgi?CMD=Get&FORMAT_TYPE=XML&RID=YOUR_RID"

# Get results in JSON
curl "https://blast.ncbi.nlm.nih.gov/blast/Blast.cgi?CMD=Get&FORMAT_TYPE=JSON2_S&RID=YOUR_RID"

# Get results in tabular format
curl "https://blast.ncbi.nlm.nih.gov/blast/Blast.cgi?CMD=Get&FORMAT_TYPE=Tabular&RID=YOUR_RID"
```

### BLAST Programs

| Program | Query → Database | Use case |
|---------|-----------------|----------|
| `blastn` | Nucleotide → Nucleotide | DNA/RNA similarity |
| `blastp` | Protein → Protein | Protein homology |
| `blastx` | Translated nuc → Protein | Find protein homologs of DNA |
| `tblastn` | Protein → Translated nuc | Find DNA encoding similar protein |
| `tblastx` | Translated nuc → Translated nuc | Compare at protein level |

### Common Databases

| Database | Content |
|----------|---------|
| `nt` | All GenBank nucleotide sequences |
| `nr` | Non-redundant protein sequences |
| `refseq_rna` | RefSeq RNA sequences |
| `refseq_protein` | RefSeq protein sequences |
| `swissprot` | UniProtKB/Swiss-Prot (curated) |
| `pdb` | Protein Data Bank sequences |

### Key Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| `PROGRAM` | BLAST program | Required |
| `DATABASE` | Target database | Required |
| `QUERY` | Sequence or accession | Required |
| `EXPECT` | E-value threshold | `10` |
| `WORD_SIZE` | Word size | `11` (blastn), `6` (blastp) |
| `HITLIST_SIZE` | Max results | `100` |
| `MATRIX` | Scoring matrix (protein) | `BLOSUM62` |
| `FILTER` | Low complexity filter | `L` |
| `ENTREZ_QUERY` | Restrict to organism | `Homo sapiens[ORGN]` |

## Python Usage

```python
import time
import requests
from xml.etree import ElementTree

BLAST_URL = "https://blast.ncbi.nlm.nih.gov/blast/Blast.cgi"


def submit_blast(sequence: str, program: str = "blastn",
                 database: str = "nt",
                 evalue: float = 0.001) -> str:
    """Submit a BLAST search, return Request ID."""
    resp = requests.post(BLAST_URL, data={
        "CMD": "Put",
        "PROGRAM": program,
        "DATABASE": database,
        "QUERY": sequence,
        "EXPECT": evalue,
        "HITLIST_SIZE": 50,
    })
    resp.raise_for_status()

    for line in resp.text.split("\n"):
        if "RID = " in line:
            return line.split("=")[1].strip()
    raise ValueError("No RID in response")


def wait_for_results(rid: str, poll_interval: int = 15,
                     max_wait: int = 300) -> bool:
    """Poll until BLAST search completes."""
    elapsed = 0
    while elapsed < max_wait:
        resp = requests.get(BLAST_URL, params={
            "CMD": "Get",
            "FORMAT_OBJECT": "SearchInfo",
            "RID": rid,
        })
        if "Status=READY" in resp.text:
            return True
        if "Status=FAILED" in resp.text:
            raise RuntimeError("BLAST search failed")
        time.sleep(poll_interval)
        elapsed += poll_interval
    raise TimeoutError(f"BLAST timed out after {max_wait}s")


def get_results(rid: str) -> list:
    """Retrieve BLAST results as parsed hits."""
    resp = requests.get(BLAST_URL, params={
        "CMD": "Get",
        "FORMAT_TYPE": "XML",
        "RID": rid,
    })
    resp.raise_for_status()

    root = ElementTree.fromstring(resp.text)
    ns = ""
    hits = []
    for hit in root.iter(f"{ns}Hit"):
        hsps = hit.find(f"{ns}Hit_hsps")
        hsp = hsps.find(f"{ns}Hsp") if hsps is not None else None
        hits.append({
            "accession": hit.findtext(f"{ns}Hit_accession", ""),
            "description": hit.findtext(f"{ns}Hit_def", ""),
            "length": int(hit.findtext(f"{ns}Hit_len", "0")),
            "evalue": float(hsp.findtext(f"{ns}Hsp_evalue", "999"))
                     if hsp is not None else 999,
            "identity": float(hsp.findtext(f"{ns}Hsp_identity", "0"))
                       if hsp is not None else 0,
            "score": float(hsp.findtext(f"{ns}Hsp_bit-score", "0"))
                    if hsp is not None else 0,
        })
    return hits


# Example: BLAST a short DNA sequence
rid = submit_blast("ATGCGATCGATCGATCGATCGATCG", program="blastn")
print(f"Submitted BLAST search: {rid}")

wait_for_results(rid)
hits = get_results(rid)
for h in hits[:5]:
    print(f"{h['accession']}: {h['description'][:60]}...")
    print(f"  E-value: {h['evalue']:.2e}

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.