UniProt REST API 查询语法与 Python 序列检索指南

What's new?

What's new?

Now you can research with Unlimited Agent Usage

UniProt REST API: Query Syntax and Sequence Search in Python

Query UniProtKB, retrieve protein sequences, and submit sequence similarity searches in Python. Then see how the SciSpace API, now in early access, connects protein identities to literature and cited evidence tables.

Getting uniprot rest api sequence search query syntax right starts with separating record retrieval from sequence comparison. UniProtKB fielded queries select protein records; downloading FASTA returns their sequences. Neither operation performs a BLAST similarity search.

This guide covers Python queries, FASTA retrieval, pagination, and BLAST submission. It then shows how the SciSpace API, now in early access, can take a protein-research product beyond annotations to cited reports and experimental evidence tables.

Which endpoint matches your sequence task?

UniProt's REST base URL ishttps://rest.uniprot.org. Its public data API requires no API key or login. Choose a route according to whether you have an accession or a query.

Task

Request

Result

---|---|---

Retrieve one record

GET /uniprotkb/{accession}?format=json

Structured annotations

Retrieve its sequence

GET /uniprotkb/{accession}?format=fasta

FASTA text

Find matching records

GET /uniprotkb/search?query=...

Paginated matches

Retrieve a query result together

GET /uniprotkb/stream?query=...

One response

These retrieval routes serve different download patterns, not different alignment algorithms. An unknown amino acid sequence belongs in a sequence analysis workflow; UniProt also distinguishes exact peptide matching from BLAST similarity search.

UniProt REST API sequence search query syntax by example

Combinefield:value clauses with uppercase Boolean operators. Use parentheses for grouping, quotes for phrases, and square brackets for ranges.

Intent

Query

---|---

Select an accession

accession:P04637

Find reviewed human TP53

gene_exact:TP53 AND organism_id:9606 AND reviewed:true

Match either gene in humans

(gene_exact:TP53 OR gene_exact:MDM2) AND organism_id:9606

Restrict sequence length

length:[300 TO 500]

Exclude fragments

organism_id:9606 NOT fragment:true

Match a protein-name phrase

protein_name:"cellular tumor antigen"

These fields are defined in UniProt's query reference.gene_exact narrows gene-name matching; reviewed:true selects reviewed entries, not a particular experimental design or level of evidence for your research question.

Build the expression first, then let your HTTP client encode it throughparams. URL encoding does not replace query-language escaping: reserved characters inside literal search values still need appropriate escaping.

Keep query fields separate from output fields

Thequery parameter selects records, while fields selects returned attributes. Search with gene_exact:TP53, but request gene_names as an output column. The return field sequence provides sequence data, not a similarity calculation.

For a compact TSV export, requestaccession,id,protein_name,gene_names,organism_name,length,sequence. Use JSON when your application needs nested annotations rather than flat columns.

Field selectors and JSON property names are not interchangeable. In a full JSON record, the accession isprimaryAccession, the organism name is under organism, and the sequence is under sequence.value. Map these explicitly in your application.

How do you retrieve protein sequences in Python?

Install Requests withpython -m pip install requests. This example selects reviewed human TP53, rejects an ambiguous result, and writes its FASTA sequence. The reference accession is P04637.

python from pathlib import Path import requests BASE = "https://rest.uniprot.org" query = "gene_exact:TP53 AND organism_id:9606 AND reviewed:true" r = requests.get(f"{BASE}/uniprotkb/search", params={"query": query, "format": "json", "size": 2}, timeout=60) r.raise_for_status() records = r.json()["results"] if len(records) != 1: raise ValueError("Select a single protein before continuing") accession = records[0]["primaryAccession"] fasta = requests.get(f"{BASE}/uniprotkb/{accession}", params={"format": "fasta"}, timeout=60) fasta.raise_for_status() Path("protein.fasta").write_text(fasta.text, encoding="utf-8") The request and format parameters follow UniProt's documented retrieval workflow.

Treat uniqueness as application policy, not a guarantee about every gene query. If several records match, show a selection screen rather than silently taking the first result.

When debugging a uniprot rest api sequence search query, inspect the accession and organism before investigating downstream sequence processing.

How do pagination and errors work?

Follow the next-page URL supplied in the HTTPLink header until it is absent. In Requests, read it with response.links.get("next", {}).get("url"); do not invent cursor values or append the original query again.

For a production UniProt client, use bounded retries for transient GET failures. Keep validation errors separate from transport failures, and retain the response body for diagnosis. UniProt documents the following status meanings.

Status

Client action

---|---

400

Fix the query, return field, or parameter

404

Check the identifier and route

500

Retry cautiously and investigate persistent failures

Save the original query, retrieval timestamp, and requested fields with your download. RecordX-UniProt-Release and compare the collected record count with X-Total-Results to help detect incomplete exports. Both headers are documented by UniProt.

How do you run an actual sequence similarity search?

Use EMBL-EBI Job Dispatcher's NCBI BLAST service for protein similarity. Its documented examples useprogram=blastp, stype=protein, and database=uniprotkb_swissprot; that database targets Swiss-Prot rather than all UniProtKB.

SetEBI_EMAIL to your contact email. This submission uses the FASTA file from the previous example and prints the job identifier:

python import os from pathlib import Path import requests BASE = "https://www.ebi.ac.uk/Tools/services/rest/ncbiblast" r = requests.post(f"{BASE}/run", data={ "email": os.environ["EBI_EMAIL"], "program": "blastp", "stype": "protein", "database": "uniprotkb_swissprot", "sequence": Path("protein.fasta").read_text(encoding="utf-8") }, timeout=60) r.raise_for_status() print(r.text.strip()) Then pollGET /status/{job_id} with a pause between checks. After FINISHED, inspect /resulttypes/{job_id} and retrieve /result/{job_id}/{type}. Handle failed jobs and enforce a local polling deadline.

For uniprot rest api sequence search documentation, keep UniProt's query references alongside Job Dispatcher's client documentation: they describe different operations.

Where does UniProt stop for a research product?

UniProt already provides annotations and literature references. The missing layer is not citations themselves, but a question-specific workflow that reads papers and compares their experimental evidence.

Imagine a target-research screen asking: “Which experiments support this protein's role in apoptosis, and where do findings disagree?” Design the output around protein identity, experimental system, perturbation, measured outcome, supporting passage, and limitations.

Building that layer yourself means maintaining literature clients, source-specific throttling and retries, PDF discovery and parsing, deduplication, ranking, summarization, and citation formatting.

The SciSpace Task API takes that research as one plain-language task. It can look up UniProt among its 77 public science databases, run one search across SciSpace's 280M+ paper index plus Google Scholar, PubMed and arXiv, then read the available full text and extract evidence.

What the SciSpace API adds for protein evidence tools

UniProt stops at protein records, annotations and literature references, and BLAST stops at alignments: neither reads the papers or compares their experimental evidence. Keep direct UniProt retrieval for exact database exports and BLAST for similarity.

The SciSpace API puts the full SciSpace Agent behind one call. It searches, reads, analyses and writes, and delivers the result as ready-to-use files.

API

What you send

What you get back

---|---|---

Search API

A research question in plain language, such as experiments on TP53's role in apoptosis

A list of papers, each with all its relevant metadata, from one search across SciSpace's 280M+ paper index plus Google Scholar, PubMed and arXiv

Task API

A research task that names the selected protein (for example UniProt P04637, human TP53), such as extracting experimental system, perturbation, outcome, supporting passage and limitations into a table, flagging conflicting findings, and writing a cited synthesis

Links to every file the agent created (Markdown, Word, PowerPoint and more) plus any supporting text answer; the plan and progress stream live, and follow-ups continue in the same thread

What this adds on top of UniProt

• Protein data plus literature in one task. Lookups across 77 public science databases such as UniProt, PDB, ClinVar, ChEMBL and PubChem, together with one search across SciSpace's 280M+ paper index plus Google Scholar, PubMed and arXiv.
• One integration. Describe the task in plain language and the agent picks the tools (search, screening, extraction, analysis, writing), instead of you maintaining literature clients, a PDF parser and an LLM.
• Evidence tables. Data-extraction tables with AI-filled columns from full text, which you can then filter, sort and combine.
• Citation chasing. Forwards and backwards from seed papers, to extend a search beyond its initial results.
• Finished files from one run. A cited synthesis as Markdown or Word, or a LaTeX report compiled to PDF with its BibTeX.
• Live streaming. Each plan step and the answer stream as they are written, and follow-ups continue in the same thread, so users can ask about conflicting findings without rebuilding the context.

When to use which

• Use UniProt directly for protein records and sequence exports, and BLAST for similarity analysis.
• Choose SciSpace for the literature workflow: cited answers, full-text evidence and paper comparison tables.

The practical lesson of uniprot rest api sequence search query syntax is to keep each step explicit. Select the protein, retrieve or compare its sequence, then investigate the evidence behind the claims your product presents.

What it doesn't do

• It is not a sequence-analysis tool. It does not run BLAST alignments or variant analysis.
• It does not read paywalled papers. It works from your own PDFs plus 50M+ open-access full texts.
• It does not query Semantic Scholar, Scopus, Web of Science, Lens or other sources not listed above.

The SciSpace API is in early access; it isn't open yet. At launch it's open to anyone: register on SciSpace and start, with no sales call. Every account gets $5 in free API credits, enough to try both APIs on real questions. The API is separate from SciSpace consumer plans; no consumer plan includes API usage.

Frequently asked questions

Last checked

UniProt and EMBL-EBI documentation checked October 21, 2026. SciSpace descriptions reflect the SciSpace API as of October 2026, which is in early access.

注意转载授权 · 阅读原文