Medication Search Implementation Guide

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.

Note: each attribute corresponds to a level of a Product Concept ID. You will see the “level” key throughout your queries and is a crucial part to 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.

What is the Multi-Step Guided Medication Search

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 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.

How to use the Multi-Step Guided Medication Search

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

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=
Copy to clipboard

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

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

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 was 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 2 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 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
Copy to clipboard

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 in 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”: two. 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
Copy to clipboard

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

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 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.

What is the One-Step Manual Input Medication Search

Dr. Smith of XYZ Medical Center wants to prescribe a medication to his patients' 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 “acemtainophen 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 amount of calls to the API as well.

How to do the One-Step Manual Input Medication Search

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:

Enter call to API as shown in the screenshot below:

https://api.drugbank.com/v1/product_concepts?q=acetaminophen 500mg oral tablet
Copy to clipboard

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.

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

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 overwritting the default settings of the product concept search step one. This means that now you can add more infomration to the query string and get accurate results instead of just level one or two Product Concept IDs.

Good to Know

• 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's a few common fields that are valuable and typically of interest:

Additional Helpful Parameters