API for SNPs

This API provides access to information about single nucleotide polymorphisms (SNPs) and other short variations in the human genome taken from the dbSNP dataset. In particular, the index behind this API is built from the newly released JSON data. The data for both assemblies GRCh37 and GRCh38 have been indexed.

Please refer to the Data Construction section for more details.

API Demo

The following demo shows how this API might be used with an autocompleter we've developed. (Example: Try typing rs123.)

For further experimentation with the autocompleter and this API, try the autocompleter demo page.

API Documentation

API Base URL: https://clinicaltables.nlm.nih.gov/api/snps/v3/search (+ query string parameters)

This data set may also be accessed through the FHIR ValueSet $expand operation.

In addition to the base URL, you will need to specify other parameters. See the query string parameters section below for details.

Query String Parameters and Default Values

At a minimum, when using the above base URL, you will need to specify the "terms" parameter containing a word or partial word to match.

Parameter NameDefault ValueDescription
terms(Required.) The search string (e.g., just a part of a word) for which to find matches in the list. More than one partial word can be present in "terms", in which case there is an implicit AND between them.
maxList Optional, with a default of 7. Specifies the number of results requested, up to the upper limit of 500. If present but the value is empty, 500 will be used.
qAn optional, additional query string used to further constrain the results returned by the "terms" field. Unlike the terms field, "q" is not automatically wildcarded, but can include wildcards and can specify field names. See the Elasticsearch query string page for documentation of supported syntax.
df rsNum, 38.chr, 38.pos, 38.alleles, 38.gene A comma-separated list of display fields (from the fields section below) which are intended for the user to see when looking at the results.
sf rsNum, 38.chr, 38.pos, 38.alleles, 38.gene A comma-separated list of fields to be searched.
cf rsNum A field to regard as the "code" for the returned item data.
efA comma-separated list of additional fields to be returned for each retrieved list item. (See the Output format section for how the data for fields is returned.) If you wish the keys in the returned data hash to be something other than the field names, you can specify an alias for the field name by separating it from its field name with a colon, e.g., "ef=field_name1:alias1,field2,field_name3:alias3,etc. Note that not every field specified in the ef parameter needs to have an alias.

SNPs Field Descriptions

FieldField Description
rsNumThe reference SNP accession number.
38.allelesThe alleles found at the SNP's position in assembly GRCh38.
38.chrThe number of the chromosome containing the SNP for assembly GRCh38.
38.posThe position of the SNP on the chromosome for assembly GRCh38
38.geneThe symbols for the genes of the SNP for assembly GRCh38.
38.assemblyThe assembly name for the SNP for assembly GRCh38, which always has the value "GRCh38"
38.seqIDThe sequence ID for the SNP for assembly GRCh38.
37.allelesThe alleles found at the SNP's position in assembly GRCh37.
37.chrThe number of the chromosome containing the SNP for assembly GRCh37.
37.posThe position of the SNP on the chromosome for assembly GRCh37
37.geneThe symbols for the genes of the SNP for assembly GRCh37.
37.assemblyThe assembly name for the SNP for assembly GRCh37, which always has the value "GRCh37"
37.seqIDThe sequence ID for the SNP for assembly GRCh37.

Output format

Output for an API query is an array of the following elements:

  1. The total number of results on the server (which can be more than the number returned). For APIs in which there are millions of records, this number might be a lower bound due to early termination if there are more than a hundred thousand results.
  2. An array of codes for the returned items. (This is the field specified with the cf query parameter above.)
  3. A hash of the "extra" data requested via the "ef" query parameter above. The keys on the hash are the fields (or their requested aliases) named in the "ef" parameter, and the value for a field is an array of that field's values in the same order as the returned codes.
  4. An array, with one element for each returned code, where each element is an array of the display strings specified with the "df" query parameter.
  5. An array, with one element for each returned code, where each element is the "code system" for the returned code. Note that only code-system aware APIs will return this array.

Sample API Queries

QueryResultDescription
https://clinicaltables.nlm.nih.gov/api/snps/v3/search?terms=rs12345 [1005, ["rs12345","rs12345559","rs1234560","rs1234510","rs1234535","rs1234544","rs1234578"], null, [ ["rs12345","22","25459491","G/A, G/C","CRYBB2P1"], ["rs12345559","4","163056329","A/G",""], ["rs1234560","1","167590377","G/A",""], ["rs1234510","2","161832116","C/T","SLC4A10"], ["rs1234535","7","84379137","A/G","SEMA3A"], ["rs1234544","X","16202873","G/A",""], ["rs1234578","11","86315280","A/C","C11orf73"]]] Returns the first 7 matches for SNPs whose rs ID begins with "rs1234".

Data Construction

This section briefly describes how a data record is constructed in this API.

The source data is the newly released JSON data from NCBI

The data construction starts from an SNP JSON record:

  1. Keep only the top level placements where the assembly's is_chromosome is true.
  2. The alleles and their positions are extracted from primary_snapshot_data.placements_with_allele.
  3. Gene symbols are extracted from primary_snapshot_data.allele_annotations
  4. The chromosome (chr) value is extracted from the seq_id, where #23 is converted to "X", #24 is converted to "Y", and #12920 is converted to "MT". In all other cases, the chr is considered empty.
  5. The data elements for assembly GRCh37 are under the field "37", which itself is a JSON object; similarly, the alleles for assembly GRCh38 are under the field "38"
  6. Within each assembly (e.g., 38), the field values (e.g., positions, alleles) for the placements are concatenated by "; " per field.