/ api

Get an association table for your list of genes

Many users look at our table view, showing which genes are associated to a specific disease:

Open Targets Platform view for asthma

But sometimes our users want to restrict this view to a list of genes they are interested in, either because they have already focussed their attention on a specific set of targets or because these targets surface in a different experiment.

Good news: our API makes this easy. One can obtain all the data behind the table view using the API and specifically the /public/association/filter call.

Get the data

For instance, to select data for the first 10 targets associated with a particular disease (eg. asthma) we can use the disease parameter with the EFO code (for asthma that is EFO_0000270) and add it at the end of the URL:


Clicking on the link in your browser, will show a very unfriendly JSON dump of our data:

You can make this view much prettier and user-friendly by installing a browser extension (there are many available for Chrome, Safari and Firefox):

Otherwise, you can download the same data as a tab separated file, by adding the format=tab parameter at the end of the URL. Notice how each parameter is separated from the previous one by an ampersand, &:


Different formats can be obtained using format=tab, format=csv and format=xml.

There is also the possibility of adding a datastructure=simple option at the end of the URL, which gives a simplified structure ready to be placed in a spreadsheet:


You can download the same results as a csv file and open it in your spreadsheet editor.

Select the fields you are interested in

If we want to select particular fields, say the overall association score, we can add the fields parameter at the end of the URL:


A list of scores is hardly useful without a description of which target and disease they are linking. We can select more data by using the parameter fields for every item we want to get:


I only want MY targets!

That is all well and good, but what we are really after is a way to get the data only for a few particular genes. Adding a target= parameter to the end of the URL solves the problem:


Notice that the target ID needs to be in the ENSGXXXXXXXXXXX format. To convert your IDs to Ensembl gene IDs, you can use our API as described in a previous post.

We can use the target parameter multiple times as &target=, until we get all the genes we are looking e.g.

https://api.opentargets.io/v3/platform/public/association/filter?disease=EFO_0000270&fields=association_score.overall&fields=target.id in addition to:


If you have too many targets to do this, the same API endpoint accepts POST methods. You need to first save a file in JSON format. For the call above, it would be:


And from the command line you can use curl to send a POST request and get a tab separated file back:

curl -X POST -d @myjsonfile.txt https://api.opentargets.io/v3/platform/public/association/filter --header "Content-Type:application/json"

This can be a very powerful way of querying our API: the JSON can be used to pass any combination of the parameters listed in our API documentation.

This was hard!

We realize this is not very user friendly, but we still wanted to show how it is possible to use the API for these kind of queries, particularly for scientists working in computational biology.

Stay tuned, we are working on making this much easier and directly accessible from our web app in our future releases!

Eliseo Papa

Eliseo Papa

ML engineer and doctor by training, looking for new ways of finding the next best targets

Read More