GraphQL API

The Open Targets Platform GraphQL — available at http://api.platform.opentargets.org — is our new API that allows for language-agnostic access to our data, along with other 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 and schema showing required and optional parameters

  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 simple query string and variables object

Our GraphQL API supports queries for a single target, disease/phenotype, drug, or target-disease association. For more systematic queries (e.g. for multiple targets), please use our data downloads or our Google BigQuery instance.

Available endpoints

The base URL endpoint for our new GraphQL API is:

https://api.platform.opentargets.org/api/v4/graphql

You can then access relevant data from the following endpoints:

/target: contains annotation information for targets including tractability assessments, mouse phenotype models, and baseline expression; also contains data on diseases and phenotypes association with the given target

/disease: contains annotation information for diseases and phenotypes including ontology, known drugs, and clinical signs and symptoms; also contains data on targets associated with the given disease or phenotype

/drug: contains annotation information for compounds and drugs including mechanisms of action, indications, and pharmacovigilance data

/search: contains index of all entities contained within the Platform

Example GraphQL query

Below is an example GraphQL query for ESR1 that you can copy and paste into our GraphQL playground.

query target{
target(ensemblId:"ENSG00000091831") {
id
approvedSymbol
approvedName
bioType
genomicLocation {
chromosome
start
end
strand
}
}
}

Using GraphQL's query strings and variables object constructs, you can also access the data using a 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 an example script using the same ESR1 query above, but written for Python and R:

Python
R
Python
#!/usr/bin/env python3
# Import relevant libraries for HTTP request and JSON formatting
import requests
import json
# Set gene_id variable
gene_id = "ENSG00000091831"
# Build query string
query_string = """
query target($ensemblId: String!){
target(ensemblId: $ensemblId){
id
approvedSymbol
approvedName
bioType
genomicLocation{
chromosome
start
end
strand
}
}
}
"""
# Set variables object of arguments to be passed to endpoint
variables = {"ensemblId": gene_id}
# Set base URL of GraphQL API endpoint
base_url = "https://api.platform.opentargets.org/api/v4/graphql"
# Perform POST request and check status code of response
r = requests.post(base_url, json={"query": query_string, "variables": variables})
print(r.status_code)
# Transform API response into JSON
api_response_as_json = json.loads(r.text)
# Print API response to terminal
print(api_response_as_json)
R
# Install relevant library for HTTP requests
library(httr)
# Set gene_id variable
gene_id <- "ENSG00000091831"
# Build query string
query_string = "
query target($ensemblId: String!){
target(ensemblId: $ensemblId){
id
approvedSymbol
approvedName
bioType
genomicLocation{
chromosome
start
end
strand
}
}
}
"
# Set base URL of GraphQL API endpoint
base_url <- "https://api.platform.opentargets.org/api/v4/graphql"
# Set variables object of arguments to be passed to endpoint
variables <- list("ensemblId" = gene_id)
# Construct POST request body object with query string and variables
post_body <- list(query = query_string, variables = variables)
# Perform POST request
r <- POST(url=base_url, body=post_body, encode='json')
# Print data to RStudio console
print(content(r)$data)

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.