dbSNP API Reference

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.

Base URLs

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

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).

E-utilities Endpoints (db=snp)

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:

json

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

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

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.

3. EFetch -- Fetch SNP details (XML only)

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.

Variation Services API

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):

json

{
  "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"
      }
    }
  ]
}

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

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

4. Batch rsID lookup (POST)

POST /variation/v0/refsnp/batch
Content-Type: application/json

{"refsnp_ids": ["334", "1805007", "7412"]}

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]

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