REST API

The Open Targets Platform REST API allows language agnostic access to data available on the Open Targets Platform. It can be accessed from the following URL:

The Open Targets Platform REST API endpoints can be divided in three methods:

  • Public - Methods that serve the core set of data e.g. associations and evidence. These methods are stable and unlikely to change.

  • Private - Methods that serve other data in the Open Targets Platform, such as the target profile page and batch search. These methods may not be stable from one release to the next. You should use these at your own risk.

  • Utils - Methods to get statistics on our data and to check if the server is alive.

These are some of the parameters for the Open Targets Platform REST API :

  • target - A target identifier listed as an Ensembl gene ID

  • disease - A disease identifier listed as EFO, Orphanet, HP, or MONDO ID

  • datasource - Data source used for target-disease associations

  • datatype - Data type used for target-disease associations

  • format - By default the results are returned in JSON but you can retrieve the results as CSV, TAB and XML (depending on the endpoint)

  • scorevalue_min - It can be used to filter (associations ou evidence) by a minimum score value. The default is 0. Scores above 0.2 is a good trade-off to filter lower quality data points

  • direct - It could be true (direct associations) or false (indirect associations)

Not sure how to apply the direct parameter in the REST API call? Check Direct versus indirect evidence: should you care? blog post for more information.

A typical Open Targets Platform REST API call can be broken down as follows:

Server

https://platform-api.opentargets.io/v3/platform/

Endpoint

e.g. public/association/filter

Parameters

e.g. ?target=ENSG00000163914&size=10000&fields=target.id&fields=disease.id

Head to the Swagger interface for a list of all available endpoints, parameters and filters.

You will also be able to test your queries in an interactive and easy manner before running your application/workflow.

Let's have a look at a few examples of endpoints, such aspublic/search, public/association and public/evidence/filter:

The search endpoint

It looks up for the Ensembl gene ID or the disease ID (EFO, HP, Orphanet, MONDO) using a free text search. It should be used to identify the best match for a disease or target of interest, rather than gathering a specific set of evidence.

Searching for DMD, for example, will return its Ensembl gene ID, ENSG00000198947, in addition to other data, such as names and IDs of orthologues, association counts, approved name and much more. You need these stable IDs to query the REST API using the remaining endpoints.

https://platform-api.opentargets.io/v3/platform/public/search?q=dmd
It allows you to look for gene or diseases of interest using a free text search, replicating the functionality of the search box in the Open Targets Platform website. It should be used to identify the best match for a disease or target, rather than gathering a specific set of evidence.
Request
Response
Request
Path Parameters
optional
string
size
Response
200: OK
{
from: 0,
took: 103,
data_version: "19.09",
query: {
highlight: true,
fields: null,
datastructure: "default",
format: "json",
size: 10
},
total: 23,
data: [
{
data: {
ortholog: {},
top_associations: {},
approved_symbol: "DMD",
description: "Anchors the extracellular matrix to the cytoskeleton via F-actin. Ligand for dystroglycan. Component of the dystrophin-associated glycoprotein complex which accumulates at the neuromuscular junction (NMJ) and at a variety of synapses in the peripheral and central nervous systems and has a structural function in stabilizing the sarcolemma. Also implicated in signaling events and synaptic transmission.",
uniprot_accessions: [],
drugs: {},
gene_family_description: "",
name_synonyms: [
"muscular dystrophy, Duchenne and Becker types",
"Dystrophin"
],
approved_name: "dystrophin",
hgnc_id: "HGNC:2928",
association_counts: {
total: 1281,
direct: 635
},
ensembl_gene_id: "ENSG00000198947",
symbol_synonyms: [
"BMD",
"DXS142",
"DXS164",
"DXS206",
"DXS230",
"DXS239",
"DXS268",
"DXS269",
"DXS270",
"DXS272"
],
biotype: "protein_coding",
full_name: "dystrophin",
type: "target",
id: "ENSG00000198947",
name: "DMD"
},
score: 2752.9067,
type: "search-object-target",
id: "ENSG00000198947",
highlight: {}
},
{},
{},
{},
{},
{},
{},
{},
{},
{}
],
size: 10
}- --

The association endpoint

It retrieves the association scores for an association between any target and disease, replicating the results seen on the website when viewing the associations for a target (e.g. NOD2) or for a disease (e.g. Noonan syndrome).

You can retrieve the association either by an ID (in the format of TARGET_ID-DISEASE_ID) or you can also use the association/filter endpoint instead.

In addition to the association scores, you will also get the data and summary on each evidence type included in the calculation of the score.

get
public/association

https://platform-api.opentargets.io/v3/platform/public/association?id=ENSG00000073756-EFO_0003767
Get the association scores for one target-disease using the association ID, in the format of `Ensembl Gene ID-disease ID` e.g. `ENSG00000073756-EFO_0003767`.
Request
Response
Request
Query Parameters
required
string
ID
Response
200: OK
{
from: 0,
took: 2,
data_version: "19.09",
query: { },
total: 1,
data: [
{
target: {},
association_score: {
datatypes: {
literature: 0.15637867953616,
rna_expression: 0.011508835806466024,
somatic_mutation: 0,
genetic_association: 0,
known_drug: 1,
animal_model: 0.27356111111111114,
affected_pathway: 0
},
overall: 1,
datasources: {
slapenrich: 0,
sysbio: 0,
expression_atlas: 0.011508835806466024,
gene2phenotype: 0,
progeny: 0,
chembl: 1,
uniprot_literature: 0,
phenodigm: 0.27356111111111114,
eva: 0,
europepmc: 0.15637867953616,
gwas_catalog: 0,
uniprot_somatic: 0,
genomics_england: 0,
postgap: 0,
uniprot: 0,
crispr: 0,
cancer_gene_census: 0,
reactome: 0,
intogen: 0,
eva_somatic: 0,
phewas_catalog: 0
}
},
max: {},
sum: {},
is_direct: true,
private: {},
disease: {},
evidence_count: {},
id: "ENSG00000073756-EFO_0003767"
}
],
size: 1
}

get
public/association/filter

https://platform-api.opentargets.io/v3/platform/public/association/filter?target=ENSG00000073756&datasource=chembl
It allows for more complex and flexible queries to get association scores and objects (e.g. filter the results by score and associated pathways, sort the results).
Request
Response
Request
Path Parameters
direct
optional
string
true
datasource
optional
string
gene2phenotype
datatype
optional
string
genetic_association
Response
200: OK

The evidence endpoint, with filters for specific data

It retrieves the evidence used for an association and allow for specific filters to be added, so that you can restrict the results by data type, data source, or limit the results to targets that are part of a given pathway. You can also specify minimum and maximum scores, as well as the format of the results (e.g. csv or xml).

get
public/evidence/filter

https://platform-api.opentargets.io/v3/platform/public/evidence/filter?target=ENSG00000088832&datasource=chembl&size=15
Request
Response
Request
Path Parameters
datatype
optional
string
genetic_association, somatic_mutation, known_drug, etc.
target
optional
string
target ID as Ensembl gene ID
size
optional
integer
number of results returned
Response
200: OK
{
from: 0,
took: 2,
next: [
1,
"ebf0bce9cc8b956ce1d2d0200756431e"
],
data_version: "19.04",
query: {},
total: 1474,
data: [],
size: 15
}

Alternative output formats, such xml, csv and tab, may be also available for some of the methods e.g. /association/filter and /search.

For complex queries with large numbers of parameters, use a POST request instead of GET. POST methods require a body (or payload) encoded as json.

You can also output these results with the following tools:

  • Command line (e.g. CURL, WGET or HTTPie)

  • Your own application and/or workflow

  • Open Targets Python client

You can also access the Open Targets Platform REST-API with scripts in R.

Check our webinar Take a rest from manual searches with the Open Targets API for an overview of the REST API and examples on some of the API queries that serve the Open Targets Platform user interface.

Please note that at the time of the recording (Dec 5th 2017), the Open Targets REST API had a different URL than the currently one in use.

You should now use:https://platform-api.opentargets.io/v3/platform

Head to the API tutorials page a few use case examples on using the Open Targets Platform REST API and email us if you have questions or want to discuss other use cases.