Skills › Scientific Agent Skills › database-lookup › ncbi-protein.md

ncbi-protein.md

107 lines · skills/database-lookup/references/ncbi-protein.md at 5f2bc03

Open on GitHub

1# NCBI Protein API Reference

NCBI Protein API Reference

Raw lines 1 to 2

3## Overview

4Protein sequence records (RefSeq, GenBank, UniProt imports) accessible via NCBI E-utilities with `db=protein`.

Overview

Protein sequence records (RefSeq, GenBank, UniProt imports) accessible via NCBI E-utilities with db=protein.

Raw lines 3 to 5

6## Base URL

7```

8https://eutils.ncbi.nlm.nih.gov/entrez/eutils/

9```

Base URL

https://eutils.ncbi.nlm.nih.gov/entrez/eutils/

Raw lines 6 to 10

11## Authentication

12- **API key** (recommended): Register at https://www.ncbi.nlm.nih.gov/account/ and append `&api_key=YOUR_KEY`.

13- Without key: 3 requests/second. With key: 10 requests/second.

14- Provide `tool` and `email` parameters for identification.

Authentication

API key (recommended): Register at https://www.ncbi.nlm.nih.gov/account/ and append &api_key=YOUR_KEY.
Without key: 3 requests/second. With key: 10 requests/second.
Provide tool and email parameters for identification.

Raw lines 11 to 15

16## Key Endpoints

Key Endpoints

Raw lines 16 to 17

18### 1. ESearch -- Search protein records

19```

20GET esearch.fcgi?db=protein&term=QUERY&retmax=N&retmode=json

21```

22| Param | Description |

23|-------|-------------|

24| `term` | Search query (Entrez syntax). Fields: `[Protein Name]`, `[Organism]`, `[Accession]`, `[Gene Name]` |

25| `retmax` | Max UIDs per response (default 20); use small batches and history for large sets. |

26| `idtype` | Set `acc` to return accession.version IDs instead of default numeric UIDs. |

27| `retstart` | Offset for pagination |

28| `usehistory` | `y` to store results on server (use with large sets) |

30**Example -- search human insulin:**

31```

32GET esearch.fcgi?db=protein&term=insulin+AND+homo+sapiens[Organism]&retmax=5&retmode=json

33```

34Response (JSON):

35```json

36{

37 "esearchresult": {

38 "count": "1523",

39 "retmax": "5",

40 "idlist": ["116734704", "1240286123", "110591076", ...],

41 "querytranslation": "insulin AND \"Homo sapiens\"[Organism]"

42 }

43}

44```

1. ESearch -- Search protein records

GET esearch.fcgi?db=protein&term=QUERY&retmax=N&retmode=json

Param	Description
`term`	Search query (Entrez syntax). Fields: `[Protein Name]`, `[Organism]`, `[Accession]`, `[Gene Name]`
`retmax`	Max UIDs per response (default 20); use small batches and history for large sets.
`idtype`	Set `acc` to return accession.version IDs instead of default numeric UIDs.
`retstart`	Offset for pagination
`usehistory`	`y` to store results on server (use with large sets)

Example -- search human insulin:

GET esearch.fcgi?db=protein&term=insulin+AND+homo+sapiens[Organism]&retmax=5&retmode=json

Response (JSON):

{
  "esearchresult": {
    "count": "1523",
    "retmax": "5",
    "idlist": ["116734704", "1240286123", "110591076", ...],
    "querytranslation": "insulin AND \"Homo sapiens\"[Organism]"
  }
}

Raw lines 18 to 45

46### 2. EFetch -- Retrieve protein records

47```

48GET efetch.fcgi?db=protein&id=IDS&rettype=TYPE&retmode=MODE

49```

50| rettype | retmode | Output |

51|---------|---------|--------|

52| `fasta` | `text` | FASTA sequence |

53| `gp` | `text` | GenPept flat file |

54| `gp` | `xml` | GenPept XML (INSDSeq) |

55| `acc` | `text` | Accession list |

56| `seqid` | `text` | SeqID list |

57| `ft` | `text` | Feature table |

59**Example -- fetch FASTA for NP_000198.1 (human insulin):**

60```

61GET efetch.fcgi?db=protein&id=NP_000198.1&rettype=fasta&retmode=text

62```

63Response:

64```

65>NP_000198.1 insulin preproprotein [Homo sapiens]

66MALWMRLLPLLALLALWGPDPAAAFVNQHLCGSHLVEALYLVCGERGFFYTPKTRREAED

67LQVGQVELGGGPGAGSLQPLALEGSLQKRGIVEQCCTSICSLYQLENYCN

68```

70**Example -- fetch GenPept XML for multiple IDs:**

71```

72GET efetch.fcgi?db=protein&id=NP_000198.1,NP_001278826.1&rettype=gp&retmode=xml

73```

2. EFetch -- Retrieve protein records

GET efetch.fcgi?db=protein&id=IDS&rettype=TYPE&retmode=MODE

rettype	retmode	Output
`fasta`	`text`	FASTA sequence
`gp`	`text`	GenPept flat file
`gp`	`xml`	GenPept XML (INSDSeq)
`acc`	`text`	Accession list
`seqid`	`text`	SeqID list
`ft`	`text`	Feature table

Example -- fetch FASTA for NP_000198.1 (human insulin):

GET efetch.fcgi?db=protein&id=NP_000198.1&rettype=fasta&retmode=text

Response:

>NP_000198.1 insulin preproprotein [Homo sapiens]
MALWMRLLPLLALLALWGPDPAAAFVNQHLCGSHLVEALYLVCGERGFFYTPKTRREAED
LQVGQVELGGGPGAGSLQPLALEGSLQKRGIVEQCCTSICSLYQLENYCN

Example -- fetch GenPept XML for multiple IDs:

GET efetch.fcgi?db=protein&id=NP_000198.1,NP_001278826.1&rettype=gp&retmode=xml

Raw lines 46 to 74

75### 3. ESummary -- Brief record summaries

76```

77GET esummary.fcgi?db=protein&id=IDS&retmode=json

78```

79Returns: accession, title, organism, length, taxonomy, create/update dates.

3. ESummary -- Brief record summaries

GET esummary.fcgi?db=protein&id=IDS&retmode=json

Returns: accession, title, organism, length, taxonomy, create/update dates.

Raw lines 75 to 80

81### 4. ELink -- Find related records

82```

83GET elink.fcgi?dbfrom=protein&db=gene&id=NP_000198.1&retmode=json

84```

85Links protein to gene, nucleotide, structure, taxonomy, etc.

4. ELink -- Find related records

GET elink.fcgi?dbfrom=protein&db=gene&id=NP_000198.1&retmode=json

Links protein to gene, nucleotide, structure, taxonomy, etc.

Raw lines 81 to 86

87## Common Search Patterns

88```

89# By accession

90term=NP_000198.1[Accession]

92# By gene name + organism

93term=BRCA1[Gene Name] AND human[Organism]

95# RefSeq only

96term=insulin AND srcdb_refseq[Properties]

98# By sequence length range

99term=100:500[Sequence Length] AND kinase[Protein Name]

100```

101

102ELink resolves protein accessions as well as numeric UIDs: the live `NP_000198.1` probe resolved UID `4557671` and Gene `3630`. Preserve both the accession version and the resolved UID in provenance.

103

Common Search Patterns

# By accession
term=NP_000198.1[Accession]

# By gene name + organism
term=BRCA1[Gene Name] AND human[Organism]

# RefSeq only
term=insulin AND srcdb_refseq[Properties]

# By sequence length range
term=100:500[Sequence Length] AND kinase[Protein Name]

ELink resolves protein accessions as well as numeric UIDs: the live NP_000198.1 probe resolved UID 4557671 and Gene 3630. Preserve both the accession version and the resolved UID in provenance.

Raw lines 87 to 103

104## Rate Limits

105- Without API key: 3 requests/second

106- With API key: 10 requests/second

107- Large batch downloads: use `usehistory=y` with `WebEnv`/`query_key`, then fetch in chunks of 500

Rate Limits

Without API key: 3 requests/second
With API key: 10 requests/second
Large batch downloads: use usehistory=y with WebEnv/query_key, then fetch in chunks of 500

Raw lines 104 to 107