Programmatic access to ClinVar data
As part of NCBI's Entrez system, ClinVar can be accessed by E-utilities, through web services and through a UNIX command line as Entrez Direct. ClinVar supports a subset of the E-utilities functions: esearch, esummary, elink, and efetch.
The general approach is:
- Use esearch to find the list of unique identifiers that return records of interest.
- esearch uses the same query language that you use to search on the website, so you can test your query on the web before automating as esearch.
- Use the identifiers returned by esearch with one of the other utilities:
- with esummary to retrieve an overview of each of those records
- with efetch to retrieve the complete record
- with elink to find data in other NCBI databases with data related to a specific ClinVar record
The default format from E-utilities is XML. For esummary, you can specify JSON output as well.
The document summary that you retrieve by esummary has more data than are displayed on the web in search results.
- For example, you can retrieve location data on both GRCh37 and GRCh38 from assembly_set , database identifiers for disorders from trait_refs, the type of variant from variant_type and the source of any gene-variant relationship from gene/source.
- For a discussion of how the data returned from esummary corresponds to objects available in our downloads, please use this overview.
Here are examples for how to use each E-utilities function in ClinVar.
| Function | Examples |
|---|---|
| Use esearch to find unique identifiers of records of interest |
find up to 500 records for the gene FGFR3 (and return results in the default XML format) https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=clinvar&term=FGFR3[gene]&retmax=500 find 500 records for the gene FGFR3, excluding variations that include multiple genes, by using the property "single_gene", and return results in the default XML format |
| Use esummary to retrieve the document summary of one of the identifiers retrieved in the previous query | https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=clinvar&id=65533 |
| Use esummary, and generate a json output |
https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=clinvar&id=65533&retmode=json |
| Use elink to determine which databases in NCBI have information related to a specific ClinVar record |
https://eutils.ncbi.nlm.nih.gov/entrez/eutils/elink.fcgi?dbfrom=clinvar&cmd=acheck&id=9 |
| Use elink to retrieve identifiers in a specific NCBI database related to a specific ClinVar record |
PubMed uids
MedGen
|
Use efetch to retrieve the XML for one or more variation records (XML that is consistent with the VCV XML) based on their id(s). Note rettype=vcv&is_variationid |
https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=clinvar&rettype=vcv&is_variationid&id=14206,41472&from_esearch=true |
| Use efetch to retrieve the XML for the most recent version of a VCV accession. Note rettype=vcv | https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=clinvar&rettype=vcv&id=VCV000014206 |
| Use efetch to retrieve the XML for a specified version of a VCV accession. Note rettype=vcv | https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=clinvar&rettype=vcv&id=VCV000014206.1 |
Use efetch to retrieve the XML for the most recent version of an RCV accession. Note rettype=clinvarset |
https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=clinvar&rettype=clinvarset&id=RCV000000606 |
Use efetch to retrieve the XML for a specified version of an RCV accession. Note rettype=clinvarset |
https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=clinvar&rettype=clinvarset&id=RCV000000606.3 |