Leverage DrugBank's Clinical API with Medication Search

Learn about the best ways you can leverage our Clinical API.

Leverage DrugBank's Clinical API with Medication Search

DrugBank’s Clinical API is a powerful tool that can be used across a vast array of use cases including everything from EMR/EHR to hospice and precision medicine. We’ve intentionally built our Clinical API to connect multiple data points across unique modules as a means of delivering specific and empowering insights to the full range of our users.

To start, we’ve outlined the best practices for the Medication Product Concepts Search.  


There are two main ways to implement the medication search:

  1. The Multi-Step Guided Medication Search: best for when end users are people from the general public (not clinically trained)
    a. Medication Search Plug and Play
    b. What is a Multi-Step Guided Medication Search
  1. One Step Manual Input Medication Search: best for when end users are clinicians (have some training in pharmaceutical products).
    a. Medication Search Plug and Play
    b. What is the One-Step Manual Input Medication Search

Table of Contents

  1. How Does the Medication Search Work
  2. Medication Search Plug and Play
  3. What is a Multi-Step Guided Medication Search
    a. How to use the Multi-Step Guided Medication Search
  4. What is the One-Step Manual Input Medication Search
    a. How to use the One-Step Manual Input Medication Search
  5. GOOD TO KNOWS
  6. Additional helpful parameters

How Does the Medication Search Work

The medication search uses Product Concepts, a hierarchically structured index of products available to easily filter or categorize a group of drugs. Using this, you have control over what drug products you are searching for based on the criteria relevant to you. This is accomplished by breaking up your drug search into four basic filters:

  • Name (generic or branded, partial names accepted)
  • Route (e.g. oral, topical, parenteral, etc.)
  • Form (e.g. tablet, capsule, liquid, etc.)
  • Strength (e.g. 50 mg, 500 mg, etc.)

Once you have found your desired identifier, you can then use that specific ID to further refine your search to map to clinical information such as indications, conditions, adverse effects, etc., without having to re-enter all of the specific drug information every time.

Example: acetaminophen 500 mg oral tablet. You can see the four attributes of that product below.

Name

Strength

Route

Form

acetaminophen

500 mg

oral

tablet


Note: each attribute corresponds to a level of a Product Concept ID. You will see the “level” key throughout your queries which is a crucial part of understanding Product Concepts.


Medication Search Plug and Play

We understand that the idea of Product Concepts can be difficult to digest. This is why we have taken the guesswork out of the equation and have developed this free-to-use DrugBank Medication Search Plugin. With this plug-and-play solution, you will be able to implement either the multi-step or one-step guided medication search in a few hours without needing to build from scratch, with some custom styling available. If you need to build your own specific search workflow, you can also use this as a template.

Download the Plugin here with a detailed implementation guide.


Here’s a quick story about how the Multi-Step Guided Medication Search can be used:

My neighbor John downloaded a spiffy app that keeps track of his medication. Unfortunately, John does not remember the strength of the medication, but he does know the brand, route, and form of the medicine. Utilizing the medication search in the app, John searched the medicine based on brand name, route, and form, while at every step, he narrowed down the strengths. Once he got to the list of available strengths, there was only one strength that matched what he remembered.

In this story, the guided medication search allowed John to combine the aspects of the drug product he was looking for, such as the drug name, route, form, and lastly strength to find the entry he wanted to be registered. At each step, he was grouping the available drugs product in the market based on their attributes. Once the entry is registered, he can then use the resulting DrugBank Product Concept ID to continue to refine his results.


In order to begin your search open your preferred API platform, we will be using Postman in our examples.

Queries all begin with a call to the DrugBank API server and must include the following:

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

This will route the query to the most current version of the DrugBank API.

Step 1

For this example, our goal is to find “acetaminophen 500 mg oral tablet.”

In order to start a medication Product Concept search, you would add the following:

https://api.drugbank.com/v1/product_concepts?q=

For the example drug acetaminophen, the call to the API would look like this:

https://api.drugbank.com/v1/product_concepts?q=acetam

The results from this API call would be:

Autocomplete: Notice how we only used part of the drug name we were looking for, “acetam”,  and the search was able to auto-complete the term. In the “hits” array, the letters that are found in between the <em> and </em> prefixes are what were matched to your query string. The remaining after the </em> is what is autocompleted. Be aware! The fewer characters you put in the search field, the more nonspecific your search results will be.

Notice the DrugBank Product Concept ID (drugbank_pcid) on line 22: DBPC0180857. This is the ID that you will now use for step two of this search. You will notice that this Product Concept ID is level: 1 at line 24. Keep an eye out on this key as you keep digging down to your final result.

NOTE: This first step will only return generic, salt, or brand medication attributes. This gets you started in your search and identifies the specific drug you are searching for via its name. If you search for acetaminophen 500 mg oral tablet here the way it is, you will only get “acetaminophen” without the remaining attributes. If you are interested in doing a non-guided, one-step search, please see One-Step Manual Input Medication Search.

TIP: For this first step, we recommend showing the “name” to create the dropdown options that an end-user can select. For the steps following, you can just focus on the key that is being populated in the API response according to the attribute you are trying to find. For example, if you are searching for “routes” then you can just display the “routes” key and what is populated there.


Step 2

Copy the ID and place it into the query after product_concepts. You will then add the next attribute: route, like this:

https://api.drugbank.com/v1/product_concepts/DBPC0180857/routes

The call and results will look like this:

Your results will display all possible routes of acetaminophen since this is what the Product Concept ID used in the query represents. Some examples of the values you might find here are intravenous and oral. For our running example, we are looking for ‘oral’. Scroll down through the results until you see the entry that is the best match.

Take note of the drugbank_pcid on line 51 in this example - DBPC0180859. This ID now includes two attributes, the drug name: ‘acetaminophen’ and route: ‘oral’.  This is why line 53 marks this as “level”: 2. We will use this specific ID to refine our product search further to include form.

TIP: Instead of always showing the “name” key for a dropdown selection, you can just show the “routes”, “forms”, or “strengths” keys from the API response. This allows a user to select the specific information that they are looking for without having to read a big text field.


Step 3

As before, copy the ID and place it into the query after product_concepts. You will then add the next product detail, form, like this:

https://api.drugbank.com/v1/product_concepts/DBPC0180859/forms

The call and results will look like this:

Once again, the call will return all possible forms of “acetaminophen, oral”. For example, you will see a capsule, liquid, and tablet to name a few. For our running example, you will need to scroll down to find what you are looking for. In this case, we want “tablet” as the form.

Take note of the drugbank_pcid on line 782 in this example - DBPC0180863. This ID now includes three attributes, the drug name: ‘acetaminophen’, route: ‘oral’, and form: ‘tablet’. There are three attributes, and therefore this is a level three Product Concept, take a look at line 784. We will use this specific ID to refine our product search further to include our last search: strength.


Step 4

As before, copy the ID and place it into the query after product_concepts. You will then add the next product detail, form, like this:

https://api.drugbank.com/v1/product_concepts/DBPC0180863/strengths.

The call and results will look like this:

You will notice that once again, the call will return all results that contain “acetaminophen, oral, tablet” so you will need to scroll down to find the strength that we are looking for - 500 mg.

The drugbank_pcid that you see on line 424 in this example is the combined ID of all attributes of this search that we have carried out—name, route, form, and strength. This is as you would have guessed, a level four Product Concept ID. This specific ID, in this case, DBPC0012414, can be used to further capture, store, and organize your data, as will be described further.

NOTE: brand and salt ingredients each add a level to the Product Concepts due to being extra attributes captured by the ID. For example, if you search for Tylenol, (acetaminophen) 500 mg oral tablet then you will end up with a level five Product Concept. When you search for the generic version, you end up with only four as per the exercise above.

TIP: Although the best practice for Product Concepts is to do the full four steps, this can also be modified to just three steps, or you can change it to capture just the information you need. Below will be the four steps and it is important to know that at any step you can either take it out of the workflow or substitute it with another step. We do recommend keeping strengths last to prevent confusing results.      

For even more information check out our Help Center documentation and Article.


                     


Dr. Smith of XYZ Medical Center wants to prescribe a medication to his patient's medical profile. He wants to add “acetaminophen 500 mg oral tablet”, quickly and in one step. He is quite busy and does not have the time to be selecting drug attributes step by step. He finds in his solution a quick Product Concept search bar and enters the full “acetaminophen 500 mg oral tablet”. The first option is exactly that, he selects this and adds it to the patient profile and prescribes the drug product right away.

In this story, the software Dr. Smith used is made with one of our versatile Product Concept searches: the One-Step Product Search. This option is available to make a product search quicker and without hurdles, especially for someone that has experience prescribing and is familiar with the terminology. This will also help reduce the number of calls to the API as well.


Drug Example: Acetaminophen 500mg oral tablet

In this example, we only want to see all Product Concepts of acetaminophen with a minimum of at least three levels (attributes). This saves time from having to get to a level three Product Concept by setting the parameter of min_level = 3. Here is how it works:

  1. Enter call to API as shown in the screenshot below:
  2. https://api.drugbank.com/v1/product_concepts?q=acetaminophen 500mg oral tablet

NOTE: If you send the API call as is right now, you will only get level one or two Product Concept IDs. This is because of the default settings in the API. To overcome this, do the following step:

2.  Enter Key ‘’min_level’’ and Value ‘’3’’ in the Query Parameters as shown below and hit send.

3.  The call will return Product Concepts results of acetaminophen with a minimum of at least three levels [as shown below]

TIP: Returns are sorted by best match to the terms searched. This means that the user will always get the closest match to the query string at the very top of the results.

TIP: The min_level parameter is overwriting the default settings of the Product Concept search step one. This means that now you can add more information to the query string and get accurate results instead of just level one or two Product Concept IDs.

For even more information check out our Help Center documentation and Article.


GOOD TO KNOWS

  • RxNorm: In the Product Concept returns, you will see that we connect to RxCUI codes. These are identifiers created by the National Library of Medicine in the US. You can use the rxCUI codes to browse the Product Concepts as well with this call:
  • https://api.drugbank.com/v1/product_concepts/rxnorm/<Enter RxCUI code here>
  • Once you have a Product Concept ID, it will be super easy to connect to all other information available in the API. This can be attained by calls such as
  • https://api.drugbank.com/v1/product_concepts/<Product Concept ID>/adverse_effects and the like. You can learn more about this here
  • Common fields in Product Concepts: Depending on what information is needed on your end, you may not require every piece of data returned by the Product Concept search. Here are a few common fields that are valuable and typically of interest:

Fields

Description

name

This will display the drug name based on the relevant product concept search

drugbank_pcid

The unique product concept ID that’s used to reach higher levels of Product Concepts or other endpoints of the database

brand

The brand of the drug product (if the product concept search was conducted with a drug brand vs the active ingredient)

level

aka the number of attributes related to the product concept ID

route

The various routes that the drug product is available in

form

The various forms that the drug product is available in

strength

The various strengths that the drug product is available in

rxnorm_concepts-->RXCUI

This is a unique code that’s standardized by NLM

ingredients→ drugbank_id

The DrugBank ID that specifies the active ingredient in the product concept. You may also capture this DBID to use in other endpoints.


Additional helpful parameters

Parameter

Default

Description

q


The text-search query string.

query_type

simple

If set to advanced, allows basic boolean operations in the query parameter q. If set to exact, only returns Product Concepts containing an exact match to the query string q.

hit_details

FALSE

If set to true, returns additional information on matched brands/ingredients/products for the concept.

level


The product concept level to filter by (optional).

min_level


The minimum product concept level to return (optional).

max_level


The maximum product concept level to return (optional).

unbranded_only

FALSE

If true, returns only Product Concepts without an associated brand.

always_ingredients

TRUE

If true, only returns Product Concepts with ingredients. Set to false to return all Product Concepts.

include_allergens

FALSE

Include allergen Product Concepts in the results.

include_vaccines

TRUE

Include vaccine Product Concepts in the results.

withdrawn

FALSE

If set to include, includes Product Concepts for which all products have been withdrawn. If set to true, includes only Product Concepts for which all products have been withdrawn. If set to false, includes only Product Concepts with at least one non-withdrawn product.

include_simple_desc

FALSE

If set to true, include simple descriptions for the product concept ingredients.

include_clinical_desc

FALSE

If set to true, include clinical descriptions for the product concept ingredients.


No matter your use case, our Clinical API provides a range of powerful tools to help you bring more certainty and speed to you and your user’s day. Depending on your specific needs it’s a good idea to explore a range of options to find the right module for you. Our customer success team has the know-how and experience to help you identify what will work best for you and guide you along the way as you get up and running.