GCI API

The GCI API currently allows user queries producing three different reports:

• Affiliations List

• GCI Summary Report

• GCI Probands Report

To be able to use the GCI API, you will need an API Key. Access to the API is limited to GCEPs. Please contact the GCEP coordinator to receive an API Key. You will also be provided with the correct URL to use.

Affiliations List

The Affiliations List returns the following information about all affiliations in JSON format:

• affiliation_id - the five-digit identifier for an affiliation, e.g. "10007"

• affiliation_fullname - the full name of the affiliation, e.g. "Hearing Loss"

• publish_approval - if approval is required, this returns "true"

• subgroups:

  • gcep

    • id - the five-digit identifier for the affiliated GCEP, e.g. "40007"

    • fullname - the full name of the GCEP, e.g. "Hearing Loss GCEP"

  • vcep

    • id - the five-digit identifier for the affiliated VCEP, e.g. "50007"

    • fullname - the full name of the VCEP, e.g. "Hearing Loss VCEP"

    • guidelines_name - the name of this VCEP's guidelines, e.g. "ClinGen Hearing Loss Expert Panel Specifications to the ACMG/AMP Variant Interpretation Guidelines Version 1"

    • guidelines_url - the URL where the guidelines can be accessed, e.g. "https://www.clinicalgenome.org/affiliation/50007/docs/assertion-criteria"

• approver - the list of official approvers, e.g.

  • 0: "Jane Doe"

  • 1: "John Smith"

How to use the API

The following input variables are required:

• API_Key: replace API_Key with your API Key

• URL: replace URL with the proper URL

• name for the output file

Example: curl -H "x-api-key:API_Key" -G "URL/affiliations?target=api" >FileName.json will return the list of ClinGen affiliations to a file named FileName.json.

GCI Summary Report

The GCI Summary Report returns the following information about each GDM curated in a specific GCEP in JSON or comma-separated value (csv) format:

• Gene: e.g. "KCNQ2"

• Disease: e.g. "undetermined early-onset epileptic encephalopathy"

• Mode of Inheritance: e.g. "Autosomal dominant inheritance (HP:0000006)"

• GCEP Affiliation: e.g. "Epilepsy GCEP"

• SOP Version: e.g. "5"

• Final Classification: e.g. "Definitive"

• Final Classification Date: e.g. "2018-06-14T14:53:52.571Z"

• Genetic Total Points: e.g. 12

• Experimental Total Points: e.g. 4

• Total Points: e.g. 16

• Proband Count: e.g. 14

• Scored Proband Count: e.g. 14

• Earliest PMID Year: e.g. "2012"

• Most Recent PMID Year: e.g. "2013"

• GDM UUID: e.g. "f33b00b8-81c5-4fa5-af66-2ca43b3b4995"

How to use the API

The following input variables are required:

• API_Key: replace API_Key with your API Key

• URL: replace URL with the proper URL

• curation status: status=published or status=approved

• time window during with the GDM was published or approved:

  • start=yyyy-mm-dd

  • end=yyyy-mm-dd

• affiliation id: use the five-digit identifier, e.g. affiliation=10005

• optional output format as csv file: -d format=csv

• name for the output file, e.g. FileName.json or FileName.csv

Example: curl -H "x-api-key:API_Key" -G "URL/snapshots" -d target=gci -d name=summary -d status=published -d start=2017-01-01 -d end=2021-09-28 -d affiliation=10005 -d format=csv >10005.csv will return the summary report for the 10005 affiliation for gene-disease records published between 1/1/2017 and 9/28/2021 to a file 10005.csv.

Alternatively, you can choose to print a count of the GDMs to the command line (i.e. no file output) using -d count:

Example: curl -H "x-api-key:API_Key" -G "URL/snapshots" -d target=gci -d name=summary -d status=published -d start=2017-01-01 -d end=2021-09-28 -d affiliation=10005 -d count will produce an output in the terminal: {"Number of curation found": "106"}

GCI Probands Report

The GCI Probands Report returns detailed information about all probands for a specific affiliation. Probands are listed by the GDM record; the output follows this format:

• Gene: e.g. "KCNQ2"

• Disease: e.g. "childhood-onset epilepsy syndrome"

• Mode of Inheritance: e.g. "Autosomal dominant inheritance (HP:0000006)"

• Status: e.g. "approved"

• Approval Date: e.g. "2021-01-25T15:10:06.266Z"

• Approval Review Date: e.g. "2017-10-20T16:00:00.000Z"

• Probands: information about each proband is listed in their own numbered section, e.g.:

  • score

    • Variant Type: e.g. "Variant is de novo"

    • Score Status: e.g. "Supports"

  • variants: list of variants associated with the proband, e.g. "NM_020822.3(KCNT1):c.2800G>A (p.Ala934Thr)"

  • label: e.g. "Male 1"

  • HPO terms: list of HPO terms, e.g. "HP:0011153" "HP:0001290"

  • HPO terms text: e.g. "Focal, generalized, and tonic seizures once per day. [...]"

  • Zygosity: e.g. "Homozygous"

  • Previous Testing Description: e.g. ""negative for SCN1A mutations. De novo mutations [...]"

  • Genotyping Methods: list of methods, e.g. "Exome sequencing"

  • PMID: e.g. "23086397"

How to use the API

The following input variables are required:

• API_Key: replace API_Key with your API Key

• URL: replace URL with the proper URL

• curation status: status=published or status=approved

• time window during with the GDM was published or approved:

  • start=yyyy-mm-dd e.g. start=2021-01-25

  • end=yyyy-mm-dd

• affiliation id: use the five-digit identifier, e.g. affiliation=10005

• name for the output file, e.g. FileName.json

Example: curl -H "x-api-key:API_Key" -G "URL/snapshots" -d target=gci -d status=approved -d start=2021-01-25 -d end=2021-07-28 -d affiliation=10007 >10007.json will return proband data from approved gene-disease records approved between 1/25/2021 and 7/28/2021 for the 10007 affililation to a file named 10007.json.

Alternatively, you can choose to print a count of the GDMs to the command line (i.e. no file output) using -d count:

Example: curl -H "x-api-key:API_Key" -G "URL/snapshots" -d target=gci -d status=approved -d start=2021-01-25 -d end=2021-07-28 -d affiliation=10007 -d count will produce an output in the terminal: {"Number of curation found": "7"}