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.

Step 1

To start a category name search, you will enter the following base URL:

https://api.drugbank.com/v1/category_names?q=
Copy to clipboard

Step 2

Enter a drug category you want to look up eg. protease inhibitors

https://api.drugbank.com/v1/category_names?q=protease inhibitors
Copy to clipboard

Autocomplete

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/DBCAT000002
Copy to clipboard

With an atc_code:

https://api.drugbank.com/v1/categories/atc/J05AE
Copy to clipboard

With a mesh_id:

https://api.drugbank.com/v1/categories/mesh/D011480
Copy to clipboard

Important Fields for Categories

Here are some common information from the category search that may be of interest:

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:

For the /drugs extension, additional information, such as references for the drugs, can be obtained by setting this parameter:​​