Categories Implementation Guide
What are categories?
Drug categories are assigned classifications to group drugs based on similar properties such as chemical taxonomy, structure, functional groups (e.g. kingdom, class), therapies, metabolism, and even mechanism of action, just to name a few. Specifically speaking, there are 3 categorization kinds for a category to be classified under:
- Therapeutic: categorization is based on the use for treatment/therapy of the drug
- Pharmacological: categorization is based on an actual property of the drug
- Indexing: categorization is based on the family tree of categories (parent/child relationships)
The categorization kind will help filter out which type of category a user might be more interested in, by separating the categories that are more clinical in nature vs. scientific or organizational.
How does the Category search work?
DrugBank's category search returns a list of possible drug categories in the database depending on the queried term.
To start a category name search, you will enter the following base URL:
https://api.drugbank.com/v1/category_names?q=Copy to clipboard
Enter a drug category you want to look up eg. protease inhibitors
https://api.drugbank.com/v1/adverse_effects?q=protease inhibitorsCopy to clipboard
In the query, the category protease inhibitors was partially queried as “protease inhibi.” The string that is in between the <em> and </em> is what is directly matched to the query, the remaining, outside of the <em> and </em>, is what is autocompleted. It's important to note that the fewer characters you input into your search and/or the more misspelled category names you type, the search will likely return more results than anticipated, which creates an unnecessarily long list of categories to filter from.
Note: Looking at this example, you can see that there's more than one hit for a category with Protease Inhibitor in its name. We'll keep our focus on the first 2 returns. In line 7, this matches directly to the category name Protease Inhibitors, and in line 53, it matches with HIV Protease Inhibitor and also a related synonym in line 57 called Inhibitors, HIV Protease.
Let's say you are interested in the category named Protease Inhibitor. On line 14, Protease Inhibitor is mapped to a DrugBank assigned category id: DBCAT000002, and external IDs such as mesh_id: D011480 in line 16 and atc_code: J05AE in line 20. The external IDs may be used for quick mapping to DrugBank's database for easier integration. You can also store the DrugBank category ID and connect to other endpoints in the API.
Another valuable point displayed is the categorization_kind in line 10. This information shows that drugs under the category Protease Inhibitor are based on 3 possible category kinds: due to their therapeutic use (line 11), based on pharmacology (line 12) and for indexing (line 13).
Tip: We aim to optimize the coverage of a drug's category name. To do so, DrugBank's category search will also return hits for any synonyms of an assigned category name that's queried. If you were to query one of the synonyms between lines 28 to 45, the category name returned in the search will be Protease Inhibitor.
Note: In this case we started off by querying a category name. Alternatively, if you already have either a DrugBank category ID or one of the supported external IDs you can call the API directly with these codes. For example:
With a Drugbank category ID:
https://api.drugbank.com/v1/categories/DBCAT000002Copy to clipboard
With an atc_code:
https://api.drugbank.com/v1/categories/atc/J05AECopy to clipboard
With a mesh_id:
https://api.drugbank.com/v1/categories/mesh/D011480Copy to clipboard
Important Fields for Categories
Here are some common information from the category search that may be of interest:
|drugbank_id||DrugBank assigned category id|
|name||The assigned category name|
|mesh_id||Unique mesh id Code of the category, useful for mapping to external ids|
|atc_code||ATC Code of the category, for mapping to external ids|
|categorization_kind||These further classifications help filter out which type of category you might be more interested in. Separating the clinical categories from just organization or more scientific categories|
|synonyms||Other commonly known category names related to the main category being queried|
|description||Brief description of the drug category|
GOOD TO KNOW
Once you have a category ID, you can use them to map to a list of related drugs in that specific category. Categories are also ordered based on a hierarchical system, it's possible to retrieve a corresponding child category (e.g. a more specific form of the category) or corresponding parent category (e.g. a more general form of the category).
Start with the basic call structure
For Drugbank category id:
https://api.drugbank.com/v1/categories/Copy to clipboard
For ATC Code:
https://api.drugbank.com/v1/categories/atc/Copy to clipboard
For Mesh ID:
https://api.drugbank.com/v1/categories/mesh/Copy to clipboard
Then add the applicable extensions to retrieve either drugs, children or parent categories related to the specified category:
|End Point||Extension||Drugbank Category ID||ATC Code||Mesh ID|
|Get a list of drugs in the particular category||/drugs||https://api.drugbank.com/v1/categories/<ID>/drugs||https://api.drugbank.com/v1/categories/atc/<ATC Code>/drugs||https://api.drugbank.com/v1/categories/mesh/<mesh ID>/drugs|
|Get list of the children categories||/children||https://api.drugbank.com/v1/categories/<ID>/children||https://api.drugbank.com/v1/categories/ac/<ATC Code>/children||https://api.drugbank.com/v1/categories/mesh/<mesh ID>/children|
|Get list of the parent categories||/parents||https://api.drugbank.com/v1/categories/<ID>/parents||https://api.drugbank.com/v1/categories/ac/<ATC Code>/parents||https://api.drugbank.com/v1/categories/mesh/<mesh ID>/parents|
For the /drugs extension, additional information, such as references for the drugs, can be obtained by setting this parameter: