Skills › Scientific Agent Skills › database-lookup › dbsnp.md

dbsnp.md

143 lines · skills/database-lookup/references/dbsnp.md at 5f2bc03

1# dbSNP API Reference

dbSNP API Reference

3## Overview

4SNP and variant data. Accessible via two APIs: NCBI E-utilities (`db=snp`) for search/metadata, and the NCBI Variation Services REST API for detailed variant annotations.

Overview

SNP and variant data. Accessible via two APIs: NCBI E-utilities (db=snp) for search/metadata, and the NCBI Variation Services REST API for detailed variant annotations.

Raw lines 3 to 5

6## Base URLs

7```

8E-utilities: https://eutils.ncbi.nlm.nih.gov/entrez/eutils/

9Variation API: https://api.ncbi.nlm.nih.gov/variation/v0/

10```

Base URLs

E-utilities:  https://eutils.ncbi.nlm.nih.gov/entrez/eutils/
Variation API: https://api.ncbi.nlm.nih.gov/variation/v0/

Raw lines 6 to 11

12## Authentication

13- **E-utilities**: API key recommended (`&api_key=KEY`). 3 req/sec without, 10 req/sec with key.

14- **Variation API**: No auth required. Rate limits apply (undocumented; be respectful, ~1-2 req/sec).

16---

Authentication

E-utilities: API key recommended (&api_key=KEY). 3 req/sec without, 10 req/sec with key.
Variation API: No auth required. Rate limits apply (undocumented; be respectful, ~1-2 req/sec).

Raw lines 12 to 17

18## E-utilities Endpoints (db=snp)

E-utilities Endpoints (db=snp)

Raw lines 18 to 19

20### 1. ESearch -- Search SNPs

21```

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

23```

25**Example -- search SNPs in BRCA1 gene:**

26```

27GET esearch.fcgi?db=snp&term=BRCA1[Gene Name] AND homo sapiens[Organism]&retmax=5&retmode=json

28```

29Response:

30```json

31{

32 "esearchresult": {

33 "count": "12847",

34 "idlist": ["80357713", "80357508", ...]

35 }

36}

37```

38Note: IDs returned are rs numbers without the "rs" prefix.

1. ESearch -- Search SNPs

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

Example -- search SNPs in BRCA1 gene:

GET esearch.fcgi?db=snp&term=BRCA1[Gene Name] AND homo sapiens[Organism]&retmax=5&retmode=json

Response:

{
  "esearchresult": {
    "count": "12847",
    "idlist": ["80357713", "80357508", ...]
  }
}

Note: IDs returned are rs numbers without the "rs" prefix.

Raw lines 20 to 39

40### 2. ESummary -- SNP summaries

41```

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

43```

45**Example -- get summary for rs334 (sickle cell variant):**

46```

47GET esummary.fcgi?db=snp&id=334&retmode=json

48```

49Response includes: `snp_id`, `chr`, `chrpos`, `genes`, `clinical_significance`, `global_mafs`, `docsum`.

2. ESummary -- SNP summaries

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

Example -- get summary for rs334 (sickle cell variant):

GET esummary.fcgi?db=snp&id=334&retmode=json

Response includes: snp_id, chr, chrpos, genes, clinical_significance, global_mafs, docsum.

Raw lines 40 to 50

51### 3. EFetch -- Fetch SNP details

52```

53GET efetch.fcgi?db=snp&id=IDS&rettype=json&retmode=text

54```

55Note: EFetch for dbSNP returns JSON with `rettype=json`. Also supports XML with `retmode=xml`.

57---

3. EFetch -- Fetch SNP details

GET efetch.fcgi?db=snp&id=IDS&rettype=json&retmode=text

Note: EFetch for dbSNP returns JSON with rettype=json. Also supports XML with retmode=xml.

Raw lines 51 to 58

59## Variation Services API

Variation Services API

Raw lines 59 to 60

61### 1. Lookup variant by rsID

62```

63GET /variation/v0/refsnp/{rsid}

64```

66**Example:**

67```

68GET https://api.ncbi.nlm.nih.gov/variation/v0/refsnp/334

69```

70Response (JSON, abbreviated):

71```json

72{

73 "refsnp_id": "334",

74 "create_date": "2000/09/19",

75 "primary_snapshot_data": {

76 "placements_with_allele": [...],

77 "allele_annotations": [...],

78 "support": [...]

79 },

80 "present_obs_movements": [

81 {

82 "component_ids": [{"type": "clinvar", "value": "..."}],

83 "observation": {

84 "seq_id": "NC_000011.10",

85 "position": 5227002,

86 "deleted_sequence": "T",

87 "inserted_sequence": "A"

88 }

89 }

90 ]

91}

92```

1. Lookup variant by rsID

GET /variation/v0/refsnp/{rsid}

Example:

GET https://api.ncbi.nlm.nih.gov/variation/v0/refsnp/334

Response (JSON, abbreviated):

{
  "refsnp_id": "334",
  "create_date": "2000/09/19",
  "primary_snapshot_data": {
    "placements_with_allele": [...],
    "allele_annotations": [...],
    "support": [...]
  },
  "present_obs_movements": [
    {
      "component_ids": [{"type": "clinvar", "value": "..."}],
      "observation": {
        "seq_id": "NC_000011.10",
        "position": 5227002,
        "deleted_sequence": "T",
        "inserted_sequence": "A"
      }
    }
  ]
}

Raw lines 61 to 93

94### 2. Lookup variant by SPDI notation

95```

96GET /variation/v0/spdi/{spdi}/rsids

97```

98SPDI format: `SeqID:Position:Deletion:Insertion`

100**Example:**

101```

102GET https://api.ncbi.nlm.nih.gov/variation/v0/spdi/NC_000011.10:5227002:T:A/rsids

103```

104

2. Lookup variant by SPDI notation

GET /variation/v0/spdi/{spdi}/rsids

SPDI format: SeqID:Position:Deletion:Insertion

Example:

GET https://api.ncbi.nlm.nih.gov/variation/v0/spdi/NC_000011.10:5227002:T:A/rsids

Raw lines 94 to 104

105### 3. Lookup variant by HGVS

106```

107GET /variation/v0/hgvs/{hgvs}/contextuals

108```

109

110**Example:**

111```

112GET https://api.ncbi.nlm.nih.gov/variation/v0/hgvs/NC_000011.10:g.5227003T>A/contextuals

113```

114

3. Lookup variant by HGVS

GET /variation/v0/hgvs/{hgvs}/contextuals

Example:

GET https://api.ncbi.nlm.nih.gov/variation/v0/hgvs/NC_000011.10:g.5227003T>A/contextuals

Raw lines 105 to 114

115### 4. Multiple rsIDs

116

117The current Variation Services schema has no `/refsnp/batch` route. For a small

118set, issue bounded individual `/refsnp/{numeric_id}` requests. For large sets,

119use [dbSNP bulk JSON](https://ftp.ncbi.nlm.nih.gov/snp/latest_release/JSON/).

120RefSNP records can be merged or withdrawn; inspect status and resolve current IDs

121before using `primary_snapshot_data`.

122

4. Multiple rsIDs

The current Variation Services schema has no /refsnp/batch route. For a small set, issue bounded individual /refsnp/{numeric_id} requests. For large sets, use dbSNP bulk JSON. RefSNP records can be merged or withdrawn; inspect status and resolve current IDs before using primary_snapshot_data.

Raw lines 115 to 122

123## Common E-utilities Search Patterns

124```

125# By rs number

126term=334[RS ID]

127

128# Clinical significance

129term=pathogenic[Clinical Significance] AND BRCA1[Gene Name]

130

131# By chromosome position (GRCh38)

132term=11[Chromosome] AND 5227002:5227002[Base Position]

133

134# By variant type

135term=missense[Function Class] AND TP53[Gene Name]

136

137# By global minor allele frequency

138term=0.01:0.05[Global MAF]

139```

140

Common E-utilities Search Patterns

# By rs number
term=334[RS ID]

# Clinical significance
term=pathogenic[Clinical Significance] AND BRCA1[Gene Name]

# By chromosome position (GRCh38)
term=11[Chromosome] AND 5227002:5227002[Base Position]

# By variant type
term=missense[Function Class] AND TP53[Gene Name]

# By global minor allele frequency
term=0.01:0.05[Global MAF]

Raw lines 123 to 140

141## Rate Limits

142- E-utilities: 3 req/sec (no key), 10 req/sec (with key)

143- Variation Services API: No published limit; recommend 1-2 req/sec

Rate Limits

E-utilities: 3 req/sec (no key), 10 req/sec (with key)
Variation Services API: No published limit; recommend 1-2 req/sec

Raw lines 141 to 143