API for COSMIC Mutation Data
This API provides information from the COSMIC mutation data set provided by the Sanger Institute. We've reduced the data set so that there is one data record per MutationID; the record from COSMIC with the most fields filled in was chosen for each Mutation ID.
Source file: the COSMIC mutation data (release: )
The following demo shows how this API might be used with an autocompleter we've developed. (Example: Try typing SP.)
For further experimentation with the autocompleter and this API, try the autocompleter demo page.
API Base URL: https://clinicaltables.nlm.nih.gov/api/cosmic/v4/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.
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 Name||Default Value||Description|
|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.|
|q||An 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||MutationID, GeneName, MutationCDS, MutationAA||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||All fields||A comma-separated list of fields to be searched.|
|cf||MutationID||A field to regard as the "code" for the returned item data.|
|ef||A 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.|
|Field||Field Description (Description text taken from the COSMIC website.)|
|AccessionNumber||The transcript identifier of the gene.|
|GeneCDS_Length||Length of the gene (base pair) counts.|
|GeneName||The gene name for which the data has been curated in COSMIC. In most cases this is the accepted HGNC identifier.|
|HGNC_ID||If gene is in HGNC, this id helps linking it to HGNC.|
|MutationAA||The change that has occurred in the peptide sequence.|
|MutationCDS||The change that has occurred in the nucleotide sequence.|
|MutationDescription||Type of mutation (substitution, deletion, insertion, complex, fusion, unknown etc.)|
|MutationGenomePosition||The genomic cooridnates of the mutation.|
|MutationStrand||Positive or negative.|
|MutationID||Unique mutation identifier, also called alternative mutation identifier in COSMIC.|
|LegacyMutationID||Legacy mutation identifier. It was called MutationID in v89 and earlier.|
|GenomicMutationID||Genomic mutation identifier,|
|Name||A field constructed by concatenating AccessionNumber, GeneName, MutationCDS and MutationID.|
|PrimaryHistology||The histological classification of the sample.|
|PrimarySite||The primary tissue/cancer from which the sample originated|
|PubmedPMID||The PUBMED ID for the paper that the sample was noted in, linking to pubmed to provide more details of the publication.|
|Site||PrimarySite and PrimaryHistology.|
Output for an API query is an array of the following elements:
- 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.
- An array of codes for the returned items. (This is the field specified with the cf query parameter above.)
- 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.
- 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.
- 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
|https://clinicaltables.nlm.nih.gov/api/cosmic/v4/search?terms=aff2||[24995,["35664913","35685107","35691722","35673444","35670952","35656831","35680716"],null,[["35664913","AFF2","c.*7015del","p.?"],["35685107","AFF2","c.*4165dup","p.?"],["35691722","AFF2","c.*7432dup","p.?"],["35673444","AFF2","c.*8067del","p.?"],["35670952","AFF2","c.*143dup","p.?"],["35656831","AFF2","c.*8057dup","p.?"],["35680716","AFF2","c.*8979C>A","p.?"]]]||Finds gene names containing "AFF2" from the COSMIC data set. Seven of 24995 Mutation IDs are returned as code fields, no extra data was requested ("ef" was not specified in the URL), and finally the four (default) display fields for each record are returned.|