Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
149 lines (98 sloc) 5.51 KB

Chemical annotation service

This page describes the reference for the MyChem.info chemical annotation web service. It's also recommended to try it live on our interactive API page.

Service endpoint

http://mychem.info/v1/chem

GET request

Obtaining the chemical annotation via our web service is as simple as calling this URL:

http://mychem.info/v1/chem/<chemid>

chemid above is any one of several common chemical identifiers: InChIKey, DrugBank accession number, ChEMBLID, ChEBI identifier, PubChem CID, UNII.

By default, this will return the complete chemical annotation object in JSON format. See here for an example and :ref:`here <chemical_object>` for more details. If the input chemid is not valid, 404 (NOT FOUND) will be returned.

Optionally, you can pass a "fields" parameter to return only the annotation you want (by filtering returned object fields):

http://mychem.info/v1/chem/KTUFNOKKBVMGRW-UHFFFAOYSA-N?fields=drugbank

"fields" accepts any attributes (a.k.a fields) available from the chemical object. Multiple attributes should be separated by commas. If an attribute is not available for a specific chemical object, it will be ignored. Note that the attribute names are case-sensitive.

Just like the chemical query service, you can also pass a "callback" parameter to make a JSONP call.

Query parameters

fields

Optional, can be a comma-separated fields to limit the fields returned from the chemical object. If "fields=all", all available fields will be returned. Note that it supports dot notation as well, e.g., you can pass "drugbank.name". Default: "fields=all".

callback

Optional, you can pass a "callback" parameter to make a JSONP call.

filter

Alias for "fields" parameter.

email

Optional, if you are regular users of our services, we encourage you to provide us an email, so that we can better track the usage or follow up with you.

Returned object

A GET request like this:

http://mychem.info/v1/chem/KTUFNOKKBVMGRW-UHFFFAOYSA-N?fields=pubchem

should return a chemical object below:

Batch queries via POST

Although making simple GET requests above to our chemical query service is sufficient in most use cases, there are some times you might find it's easier to batch query (e.g., retrieving chemical annotations for multiple chemicals). Fortunately, you can also make batch queries via POST requests when you need:

URL: http://mychem.info/v1/chem
HTTP method:  POST

Query parameters

ids

Required. Accept multiple chemical ids separated by comma, e.g., "ids=SDUQYLNIPVEERB-QPPQHZFASA-N,SESFRYSPDFLNCH-UHFFFAOYSA-N,SHGAZHPCJJPHSC-ZVCIMWCZSA-N". Note that currently we only take the input ids up to 1000 maximum, the rest will be omitted.

fields

Optional, can be a comma-separated fields to limit the fields returned from the matching hits. If “fields=all”, all available fields will be returned. Note that it supports dot notation as well, e.g., you can pass "drugbank" or "drugbank.name". Default: "all".

email

Optional, if you are regular users of our services, we encourage you to provide us an email, so that we can better track the usage or follow up with you.

Example code

Unlike GET requests, you can easily test them from browser, make a POST request is often done via a piece of code, still trivial of course. Here is a sample python snippe using httplib2 modulet:

import httplib2
h = httplib2.Http()
headers = {'content-type': 'application/x-www-form-urlencoded'}
params = 'ids=SDUQYLNIPVEERB-QPPQHZFASA-N,SESFRYSPDFLNCH-UHFFFAOYSA-N&fields=drugbank.name'
res, con = h.request('http://mychem.info/v1/chem', 'POST', params, headers=headers)

or this example using requests module:

import requests
params = {'ids': 'SDUQYLNIPVEERB-QPPQHZFASA-N,SESFRYSPDFLNCH-UHFFFAOYSA-N', 'fields': 'drugbank.name'}
res = request.post('http://mychem.info/v1/chem', params)
con = res.json()

Returned object

Returned result (the value of "con" variable above) from above example code should look like this:

[
  {
    "_id": "SDUQYLNIPVEERB-QPPQHZFASA-N",
    "query": "SDUQYLNIPVEERB-QPPQHZFASA-N",
    "drugbank": {
      "_license": "http://bit.ly/2PSfZTD",
      "name": "Gemcitabine"
    }
  },
  {
    "_id": "SESFRYSPDFLNCH-UHFFFAOYSA-N",
    "query": "SESFRYSPDFLNCH-UHFFFAOYSA-N",
    "drugbank": {
      "_license": "http://bit.ly/2PSfZTD",
      "name": "Benzyl Benzoate"
    }
  }
]