GraphQL API

The Open Targets Genetics Portal API is a GraphQL API that powers the user interface and that supports language-agnostic access to our data.
Compared to a REST API, our GraphQL API offers five key benefits:
1.You can construct a query that returns only the fields that you need
2.You can build graphical queries that traverse a data graph through resolvable entities and this reduces the need for multiple queries
3.You can access the GraphQL API playground with built-in documentation to build your query and run it in real-time 
4.You can view the schema that shows the available fields for each object along with a description and data type attribute 
5.You only have to use POST requests with a query string and variables object
Available endpoints
The base URL endpoint for the Genetics Portal GraphQL API is:
1
https://api.genetics.opentargets.org/graphql
Copied!
Our GraphQL API supports queries for a single variant, gene, study, or study-variant pair. For more systematic queries (e.g. for multiple variants), please use our data downloads or our Google BigQuery instance - open-targets-prod.
Sample GraphQL query
Below is a sample GraphQL API query for the Locus2Gene data for FINNGEN_R5_E4_DM2 (Type 2 diabetes) and 11_72752390_G_A that you can run in the GraphQL API browser.
The query will recreate the data table available in the "Gene prioritisation using locus-to-gene pipeline" section on the FINNGEN_R5_E4_DM2 and 11_72752390_G_A study-locus page.
1
query genePrioritisationUsingL2G {
2
  studyLocus2GeneTable(studyId: "FINNGEN_R5_E4_DM2", variantId: "11_72752390_G_A") {
3
    rows {
4
      gene {
5
        symbol
6
        id
7
      }
8
      yProbaModel
9
      yProbaDistance
10
      yProbaInteraction
11
      yProbaMolecularQTL
12
      yProbaPathogenicity
13
      hasColoc
14
      distanceToLocus
15
    }
16
  }
17
}
Copied!
Using GraphQL's query strings and variables object constructs, you can also access the data using any programming language that supports HTTP POST requests. While this is a valid approach, we discourage users from repeatedly querying the GraphQL API one entity at a time. Instead, our comprehensive datasets available for download provide a simpler and more performant strategy to achieve the same result.
Sample scripts
Below is a sample script in Python for the same sample query above -  FINNGEN_R5_E4_DM2 (Type 2 diabetes) and 11_72752390_G_A.
Python
R
1
#!/usr/bin/env python3
2
​
3
# Import relevant libraries for HTTP request and JSON formatting
4
import requests
5
import json
6
​
7
# Set study_id and variant_id variables
8
study_id = "FINNGEN_R5_E4_DM2"
9
variant_id = "11_72752390_G_A"
10
​
11
# Build query string
12
query_string = """
13
  query genePrioritisationUsingL2G($myVariantId: String!, $myStudyId: String! ){
14
    studyLocus2GeneTable(studyId: $myStudyId, variantId: $myVariantId){
15
      rows {
16
        gene {
17
          symbol
18
          id
19
        }
20
        yProbaModel
21
        yProbaDistance
22
        yProbaInteraction
23
        yProbaMolecularQTL
24
        yProbaPathogenicity
25
        hasColoc
26
        distanceToLocus
27
      }
28
    }
29
  }
30
"""
31
​
32
# Set variables object of arguments to be passed to endpoint
33
variables = {"myVariantId": variant_id, "myStudyId": study_id}
34
​
35
# Set base URL of Genetics Portal GraphQL API endpoint
36
base_url = "https://api.genetics.opentargets.org/graphql"
37
​
38
# Perform POST request and check status code of response
39
r = requests.post(base_url, json={"query": query_string, "variables": variables})
40
print(r.status_code)
41
​
42
# Transform API response into JSON 
43
api_response_as_json = json.loads(r.text)
44
​
45
# Print first element of JSON response data
46
print(api_response_as_json["data"]["studyLocus2GeneTable"]["rows"][0])
Copied!
1
# Install relevant library for HTTP requests
2
library(httr)
3
​
4
# Set study_id and variant_id variables
5
study_id <- "FINNGEN_R5_E4_DM2"
6
variant_id <- "11_72752390_G_A"
7
​
8
# Build query string
9
query_string = "
10
  query genePrioritisationUsingL2G($myVariantId: String!, $myStudyId: String! ){
11
    studyLocus2GeneTable(studyId: $myStudyId, variantId: $myVariantId){
12
      rows {
13
        gene {
14
          symbol
15
          id
16
        }
17
        yProbaModel
18
        yProbaDistance
19
        yProbaInteraction
20
        yProbaMolecularQTL
21
        yProbaPathogenicity
22
        hasColoc
23
        distanceToLocus
24
      }
25
    }
26
  }
27
"
28
​
29
# Set base URL of Genetics Portal GraphQL API endpoint
30
base_url <- "https://api.genetics.opentargets.org/graphql"
31
​
32
# Set variables object of arguments to be passed to endpoint
33
variables <- list("myStudyId" = study_id, "myVariantId" = variant_id)
34
​
35
# Construct POST request body object with query string and variables
36
post_body <- list(query = query_string, variables = variables)
37
​
38
# Perform POST request
39
r <- POST(url=base_url, body=post_body, encode='json')
40
​
41
# Print first entry of L2G data to RStudio console
42
head(content(r)$data$studyLocus2GeneTable$rows, 1)
Copied!
Tutorials and how-to guides
For more information on how to use the GraphQL API and example queries based on actual use cases and research questions, check out the Open Targets Community.

Data access - Previous

Data Download

Last modified 4mo ago

Copy link

Contents

Available endpoints

Sample GraphQL query

Sample scripts

Tutorials and how-to guides