NAV

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=

Step 2

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

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

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

With an atc_code:

https://api.drugbank.com/v1/categories/atc/J05AE

With a mesh_id:

https://api.drugbank.com/v1/categories/mesh/D011480

Important Fields for Categories

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

FieldsDescription
drugbank_idDrugBank assigned category id
nameThe assigned category name
mesh_idUnique mesh id Code of the category, useful for mapping to external ids
atc_codeATC Code of the category, for mapping to external ids
categorization_kindThese 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
synonymsOther commonly known category names related to the main category being queried
descriptionBrief 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/

For ATC Code:

https://api.drugbank.com/v1/categories/atc/

For Mesh ID:

https://api.drugbank.com/v1/categories/mesh/

Then add the applicable extensions to retrieve either drugs, children or parent categories related to the specified category:

End PointExtensionDrugbank Category IDATC CodeMesh ID
Get a list of drugs in the particular category/drugshttps://api.drugbank.com/v1/categories/<ID>/drugshttps://api.drugbank.com/v1/categories/atc/<ATC Code>/drugshttps://api.drugbank.com/v1/categories/mesh/<mesh ID>/drugs
Get list of the children categories/childrenhttps://api.drugbank.com/v1/categories/<ID>/childrenhttps://api.drugbank.com/v1/categories/ac/<ATC Code>/childrenhttps://api.drugbank.com/v1/categories/mesh/<mesh ID>/children
Get list of the parent categories/parentshttps://api.drugbank.com/v1/categories/<ID>/parentshttps://api.drugbank.com/v1/categories/ac/<ATC Code>/parentshttps://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:​​

ParameterDefaultDescription
include_referencesfalseIf true, includes the lists of references for each drug.