Search Interactions

The interactions endpoint can be used to return interactions for a given set of gene or drug names/symbols. It also allows you to filter returned interactions.

/api/v1/interactions.json

Note: While the preferred method for accessing this endpoint is a GET request, it will also accept POST requests to accommodate large gene lists if needed.

Accepted Parameters:

Example Call:

Note: The following example would query DGIdb for interactions involving the genes FLT1, STK1, and FAKE. It will only show interactions with antineoplastic drugs reported by the source. TALC.

http://dgidb.org/api/v1/interactions.json?genes=FLT1,MM1,FAKE&drug_types=antineoplastic&interaction_sources=TALC

Example Response:

The response will come back with two top level items:

matchedTerms will be a list containing a hash for each search term that you provided that we were able to map unambiguously to an Entrez gene. Each hash will contain your original search term, the Entrez long and full names that DGIdb matched them to as well as a list of categories that the given gene is in. Additionally, the hash will contain a list of drug interactions for the gene. This list includes interaction type information as well as the drug name and source that reported the interaction.

unmatchedTerms will be a list containing a hash for each search term that you provided that we were unable to map definitiely to a single Entrez gene. Each hash will contain both the orignal search term and a list of possible suggestions if the search term was ambiguous.

"matchedTerms":[
  {
    "searchTerm":"FLT3",
    "geneName":"FLT3",
    "geneLongName":"fms-related tyrosine kinase 3",
    "geneCategories":[
      "TYROSINE KINASE",
      "DRUGGABLE GENOME",
      "KINASE",
      "CELL SURFACE"
    ],
    "interactions":[
      {
        "interactionId":"61577575-b8ec-4916-a25f-edb362047b97",
        "interactionType":"inhibitor",
        "drugName":"SORAFENIB",
        "source":"TALC"
      },
      {
        "interactionId":"318383b3-3cd5-478d-ada2-f26977caf8eb",
        "interactionType":"inhibitor",
        "drugName":"AMUVATINIB",
        "source":"TALC"
      },
      {
        "interactionId":"a961d382-4b52-435f-a610-f27673184b09",
        "interactionType":"inhibitor",
        "drugName":"SUNITINIB",
        "source":"TALC"
      },
      {
        "interactionId":"e3b974f9-cfce-4fa7-9dec-80643c84a571",
        "interactionType":"inhibitor",
        "drugName":"AS703569",
        "source":"TALC"
      },
      {
        "interactionId":"a211e2dc-7e76-45f9-a031-0ad7b24a5ea0",
        "interactionType":"inhibitor",
        "drugName":"XL999",
        "source":"TALC"
      },
      {
        "interactionId":"8732ec65-58bb-4dfa-a82d-a335f67bc051",
        "interactionType":"inhibitor",
        "drugName":"ENMD-0276",
        "source":"TALC"
      }
    ]
  }
],
"unmatchedTerms":[
  {
    "searchTerm":"MM1",
    "suggestions":[
      "PFDN5",
      "PLXNB2"
    ]
  },
  {
    "searchTerm":"FAKE",
    "suggestions":[

    ]
  }
]}

Interaction Types

The interaction types endpoint can be used to retrieve a current list of supported interaction types for use in the interactions endpoint.

http://dgidb.org/api/v1/interaction_types.json

Example Response:

["activator", "inhibitor", "unknown"]

Interaction Sources

The interaction sources endpoint can be used to retrieve a current list of supported interaction sources for use in calls to the interactions endpoint.

http://dgidb.org/api/v1/interaction_sources.json

Example Response:

["DrugBank","PharmGKB","TALC","TEND","TTD"]

Drug Types

The drug types endpoint can be used to retrieve a current list of supported drug types for use in calls to the interactions endpoint.

http://dgidb.org/api/v1/drug_types.json

Example Response:

["antineoplastic"]

Gene Categories

The gene categories endpoint can be used to retrieve a current list of supported gene categories for use in calls to the interactions endpoint.

http://dgidb.org/api/v1/gene_categories.json

Example Response:

["KINASE", "DNA REPAIR", "TUMOR SUPPRESSOR"]

Source Trust Levels

The source trust levels endpoint can be used to retrieve a current list of supported source trust levels for use in calls to the interactions endpoint.

http://dgidb.org/api/v1/source_trust_levels.json

Example Response:

["Expert curated", "Non-curated"]

Genes in Category

The Genes in Category endpoint can be used to get a list of all genes in DGIdb that are known to be in a specific category.

/api/v1/genes_in_category.json

Accepted Parameters:

Example Call:

Note: The following example would query DGIdb for a list of genes known to be Kinases

http://dgidb.org/api/v1/genes_in_category.json?category=kinase

Example Response:

["SNRK","BCR","FKBP1A","TAB2","DGKE","PHKA1","PRKCH"]

Formats

Currently, all API responses are provided only in JSON. If you are experimenting with the API in your browser and you want to improve the display for JSON output you use a JSON formatter such as this one.

Status Codes

The DGIdb API can respond to requests with a number of status codes. They are explained in the table below.

Perl

A sample Perl application that interacts with DGIdb can be found on github.

Use the command line script to search for interactions FLT3 or EGFR, and limit to drugs that act as inhibitors:
EXECUTE EXAMPLE SCRIPT

wget https://raw.github.com/genome/dgi-db/master/files/perl_example.pl
chmod +x perl_example.pl
./perl_example.pl --genes='FLT3,EGFR' --interaction_types='inhibitor'

You may need to install the 'json' package from cpan before this script will work.
On a mac you can do the following:

First configure the 'cpan' tool:

sudo cpan

get JSON
make JSON
install JSON
q

Python

A sample Python application that interacts with DGIdb can be found on github.

Use the command line script to search for interactions FLT3 or EGFR, and limit to drugs that act as inhibitors:
EXECUTE EXAMPLE SCRIPT

wget https://raw.github.com/genome/dgi-db/master/files/python_example.py
chmod +x python_example.py
./python_example.py --genes='FLT3,EGFR' --interaction_types='inhibitor'

This example uses the 'requests' python library. Installing 'requests' is easiest with 'pip' which is one of the easiest and recommended ways to install Python packages.:

sudo pip install requests

wget https://raw.github.com/pypa/pip/master/contrib/get-pip.py
sudo python get-pip.py

Ruby

A small Ruby client library, along with a short usage demo can be found on github.

Use the client library to search for interactions involving FLT3 or EGFR, only from trusted sources:
SAMPLE CODE

client = DgidbApiClient.new
query_params = { source_trust_levels: 'Expert curated', genes: 'FLT3,EGFR' }
interaction_results = client.query(:interactions, query_params)

wget https://raw.github.com/genome/dgi-db/master/files/ruby_example.rb
ruby ruby_example.rb

Shell

A small tutorial showing command-line usage of the DGIdb API using shell commands on github.

Try the following examples from the command line to view and format output from the API:
SAMPLE CODE

curl http://dgidb.org/api/v1/interactions.json

curl http://dgidb.org/api/v1/interactions.json?genes=FLT3

curl http://dgidb.org/api/v1/interactions.json?genes=FLT3 | python -mjson.tool

curl http://dgidb.org/api/v1/interactions.json?genes=FLT3,STK1,FAKE1 | python -mjson.tool

curl http://dgidb.org/api/v1/interactions.json?genes=STK1,FAKE1 | python -mjson.tool

curl http://dgidb.org/api/v1/interactions.json?genes=STK1,FAKE1 | python -mjson.tool

curl http://dgidb.org/api/v1/interactions.json?genes=FLT3,STK1,FAKE1\&interaction_sources=TTD,DrugBank | python -mjson.tool

curl http://dgidb.org/api/v1/interactions.json?genes=FLT3,STK1,FAKE1\&interaction_sources=TTD,DrugBank\&interaction_type=inhibitor | python -mjson.tool