API Documentation

Basic call

Say you'd like data on three variants in the database. This is the most basic call:

http://deafnessvariationdatabase.org/api?terms=chr6:25850845,chr4:88533540,chr2:179325735

And here's the output

#id hgvs_protein_change hgvs_nucleotide_change  variantlocale variation               ...
1562	NM_006632:p.Gly201Arg	NM_006632:c.601G>A	EXON7	chr6:25850845:C>T	...
249	NM_014208:p.Arg68Trp	NM_014208:c.202A>T	EXON4	chr4:88533540:A>T	...
2193	NM_001042702.3:p.Arg265Gly	NM_001042702.3:c.793C>G	EXON7	chr2:179325735:C>G	...

You'll see a lot more columns, but that should give you an idea. By default,

  • The output MIME is text/plain
  • The output format is tab-delimited
  • Data is from the most recent version of the database (currently 8)

Fields

Regular Fields
Field Explanation Field Explanation
id Internal; used to organize data. hgvs_protein_change HGVS Protein Change
hgvs_nucleotide_change HGVS Nucleotide Change variantlocale Exonic or Intronic position of variant
variation HGVS Genomic Position pathogenicity Pathogenicity
disease Disease pubmed_id Pubmed ID
dbsnp dbSNP ID gene Gene
phylop_score PhyloP Score phylop_pred PhyloP Prediction
sift_score SIFT Score sift_pred SIFT Prediction
polyphen2_score PolyPhen2 Score polyphen2_pred PolyPhen2 Prediction
lrt_score LRT Score lrt_pred LRT Prediction
mutationtaster_score MutationTaster Score mutationtaster_pred MutationTaster Prediction
gerp_rs GERP++ Rejected Substitutions Score gerp_nr GERP++ Neutral Rate
gerp_pred GERP++ Prediction

For the table below, fields prefixed with

The fields also come in pairs: {field}_ac and {field}_an. Fields suffixed with “ac” show allele count, while those with “an” show total allele count. For example, tb_ibs_ac shows 1000 Genomes allele counts for Iberian populations in Spain.

Population Frequency Fields
Field Population Field Population
evs_ea_* European American Alternate Allele Count evs_aa_* African American Total Allele Count
tg_acb_* African Caribbean in Barbados tg_asw_* African Ancestry in Southwest US
tg_cdx_* Chinese Dai in Xishuangbanna tg_ceu_* Utah residents, Northern and Western European ancestry
tg_chb_* Han Chinese in Beijing, China tg_chs_* Han Chinese South
tg_clm_* Colombian in Medellin, Colombia tg_fin_* Finnish from Finland
tg_gbr_* British from England and Scotland tg_gih_* Gujarati Indian in Houston, TX
tg_ibs_* Iberian populations in Spain tg_jpt_* Japanese in Toyko, Japan
tg_khv_* Kinh in Ho Chi Minh City, Vietnam tg_lwk_* Luhya in Webuye, Kenya
tg_mxl_* Mexican Ancestry in Los Angeles, CA tg_pel_* Peruvian in Lima, Peru
tg_pur_* Puerto Rican in Puerto Rico tg_tsi_* Toscani in Italia
tg_yri_* Yoruba in Ibadan, Nigeria otoscope_* OtoSCOPE®

Tweaking the Call

List of API parameters
Tweak Description Append to call Possible values Default Value
(i.e. if unspecified)
Search Type Search by genomic position or by gene.
  • position will perform a fuzzy search, while exactposition won’t.
  • genelist doesn’t require search terms and will give you a list of all genes and the number of variants per gene.
  • This is true for variantlist list, which will give you a full list of all variants (and nothing else) in the database.
&type=
  • position
  • exactposition
  • gene
  • genelist
  • variantlist
position
Output Format Format results as JSON, XML, comma-separated (CSV) or tab-delimited values. Please note that the vcf output type is for type variantlist only. &format=
  • json
  • xml
  • csv
  • tab
  • vcf
tab
Output Method If set to download, headers appropriate for the chosen output format are sent to the client. If unspecified or set explicitly to plain, the output sent as plain text (the text/plain MIME-type.) &method=
  • plain
  • download
plain
Data Version Specify a particular version the database that you would like to retrieve data for. &version= See the “Versions” table below. 8

Versions

Version Variants Genes Updated
1 14,983 61 2012-08-07 13:16:54
2 14,983 61 2012-12-17 21:19:58
2.1 15,118 69 2014-04-22 16:05:57
3 147,772 84 2014-09-25 00:00:00
3.1 147,771 84 2015-02-04 14:22:10
6 1,366,364 115 2015-05-15 13:17:25
6.1 502,198 117 2015-07-27 17:35:28
7 811,251 135 2016-04-21 11:50:02
8 876,410 152 2016-12-06 13:41:00

Examples

To display JSON-formatted results, simply add &format=json to the call

http://deafnessvariationdatabase.org/api?terms=chr6:25850845,chr10:88533540&format=json

Here's the output in plain text:

  {
      "chr6:25850845":{
          "pathogenicity":"Pathogenic",
          "disease":"Glycogen storage disease 1c ?",
          "pubmed_id":"15505377",
          .
          .
          .
      },
      "chr4:88533540":{
          "pathogenicity":"probable-pathogenic",
          "disease":"",
          "pubmed_id":"",
          .
          .
          .
      }
  }

To download the search results in CSV format,

http://deafnessvariationdatabase.org/api?terms=chr6:25850845,chr10:73375330&format=csv&method=download

To get all variants for the gene GJB6 in XML

http://deafnessvariationdatabase.org/api?terms=gjb6&type=gene&format=xml&method=download

To get all genes and number of variants per gene in JSON

http://deafnessvariationdatabase.org/api?&type=genelist&format=json


Support

Please get in touch if you experience any issues with API access.