ContextQMD
Back to Claude Scientific Skills

ClinVar API Reference

scientific-skills/database-lookup/references/clinvar.md

2.38.03.1 KB
Original Source

ClinVar API Reference

Base URLs

  • NCBI E-utilities: https://eutils.ncbi.nlm.nih.gov/entrez/eutils
  • ClinVar web API (VCV): https://www.ncbi.nlm.nih.gov/clinvar
  • NCBI Variation Services: https://api.ncbi.nlm.nih.gov/variation/v0

Authentication

  • E-utilities: No key required, but strongly recommended. Register at https://www.ncbi.nlm.nih.gov/account/ to get an api_key.
  • Without key: 3 requests/second. With key: 10 requests/second.
  • Append &api_key=YOUR_KEY to all E-utility requests.

Rate Limits

  • Without API key: 3 req/sec
  • With API key: 10 req/sec

Key Endpoints

1. Search ClinVar (esearch)

GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=clinvar&term={query}&retmode=json

Example — search for BRCA1 pathogenic variants:

GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=clinvar&term=BRCA1[gene]+AND+pathogenic[clinical_significance]&retmode=json&retmax=10

Returns JSON with idlist of ClinVar Variation IDs.

2. Fetch ClinVar Records (esummary)

GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=clinvar&id={id_list}&retmode=json

Example:

GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=clinvar&id=37088,37087&retmode=json

Returns JSON with clinical significance, variant name, gene, conditions, review status.

3. Full Record (efetch)

GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=clinvar&id={id}&rettype=vcv&is_variationid&retmode=xml

Note: ClinVar efetch returns XML only (no JSON for efetch).

4. Variation Services API — SPDI/HGVS Lookup

GET https://api.ncbi.nlm.nih.gov/variation/v0/spdi/{spdi_expression}/clinvar
GET https://api.ncbi.nlm.nih.gov/variation/v0/hgvs/{hgvs_expression}/clinvar

Example:

GET https://api.ncbi.nlm.nih.gov/variation/v0/hgvs/NM_007294.4%3Ac.5266dupC/clinvar

5. ClinVar VCV/RCV Direct Access

GET https://www.ncbi.nlm.nih.gov/clinvar/variation/{variation_id}/?redir=vcv

This returns HTML. For programmatic access, use E-utilities or the Variation Services API.

Useful Search Qualifiers

  • [gene] — gene symbol (e.g., BRCA1[gene])
  • [clinical_significance] — pathogenic, likely_pathogenic, benign, uncertain_significance
  • [molecular_consequence] — missense, nonsense, frameshift, etc.
  • [review_status] — criteria_provided_single_submitter, reviewed_by_expert_panel, etc.
  • [condition] — disease name

Response Format

  • esearch/esummary: JSON (with retmode=json)
  • efetch: XML only for ClinVar
  • Variation Services: JSON

esummary Response Key Fields

json
{
  "result": {
    "37088": {
      "uid": "37088",
      "title": "NM_007294.4(BRCA1):c.5266dupC (p.Gln1756Profs*74)",
      "clinical_significance": { "description": "Pathogenic" },
      "genes": [{"symbol": "BRCA1", "geneid": 672}],
      "variation_set": [...],
      "trait_set": [{"trait_name": "Hereditary breast and ovarian cancer syndrome"}]
    }
  }
}

Notes