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. 1.
    You can construct a query that returns only the fields that you need
  2. 2.
    You can build graphical queries that traverse a data graph through resolvable entities and this reduces the need for multiple queries
  3. 3.
    You can access the GraphQL API playground with built-in documentation to build your query and run it in real-time
  4. 4.
    You can view the schema that shows the available fields for each object along with a description and data type attribute
  5. 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.
Last modified 4mo ago