API Manual


Query Syntax

The API processor is located at : https://api.crediblemeds.org/index.php/tools/json . All queries are to be executed via a secure SSL connection.

Queries to the CredibleMeds API are made up of parameters joined by an ampersand &. Each parameter is followed by an equal sign = and an argument.

Searches have a special syntax: search=field:term. Note that there is only one equal sign = and there is a colon : between the field to search, and the term to search for.

Pattern Description
search=field:term Search within a specific field for a term. 
search=field:term+[AND]+field:term Search for records that match two terms.
search=field:term+field:term Search for records that match either of two terms.

Spaces
Queries use the plus sign + in place of the space character. Wherever you would use a space character, use a plus sign instead.

Exact matches
For exact matches, use double quotation marks " " around the words. For example, "multiple+myeloma".

Grouping
To group several terms together, use parentheses ( ). For example, (drug.generic_name:Ritonavir+Escitalopram). Terms separated by plus signs + are treated as in a boolean OR.

To join terms as in a boolean AND, use the +[AND]+. For example, (drug.risk_category:P+C)+AND+drug.class:SSRI results are drugs from TdP risk categories "Possible Risk" or "Conditional Risk" that match drug class keyword – SSRI (for exact match use drug.class:"SSRI" )

Dates and ranges
The CredibleMeds API supports searching by range in date or numeric.

Specify an inclusive range by using (field.term:min+[TO]+max). These include the values in the range. For instance, 2004-01-01+TO+2005-01-01 will search for records between Jan 1, 2004 and Jan 1, 2005.

Query Parameters

Section Description Example
api_key An API key is required to make calls to CredibleMeds Api ?api_key={your_api_key}
display_mode Lists the query output in human readable format &search=list:dta&display_mode
search What to search for, in which fields.  &search=drug.risk_category:C
limit (Optional)Return up to this number of records that match the search parameter. &limit=10
skip (Optional)Skip this number of records that match the search parameter, then return the matching records that follow. &skip=30
filter (Optional)Output custom results fields. Fields names should be separated by '+' &filter=Generic_Name+Category+TherapeuticUse

Searchable Endpoints

The search functionality for the drugs database information is organised on a two levels structure and for practical uses, the search functionality is limited to the following endpoints:

Search Endpoints: Level 1

Endpoint Description Values Example
 list Return bulk list, depending on list type  passed as argument. Does not accept other search parameters.
  • dta - drugs to avoid list
  • composite- drugs included in first 3 categories
&search=list:dta
&search=list:composite
 drug Return drugs which match search parameters.Requires level 2 endpoints  - &search=drug.risk_category=P

Search Endpoints: Level 2

Endpoint Description Values Example
generic_name Generic name of the drug Any generic name &search=drug.generic_name:Albuterol
brand Brand name Any brand name &search=drug.brand:Dexedrine
class * Drug class Any drug class &search=drug.class:Anti-depressant
therapeutic_use * Drug therapeutic use Any therapeutic use &search=drug.therapeutic_use.:ADHD
risk_category TdP risk category R – Known risk of TdP
P – Possible risk of TdP
C – Conditional risk of TdP
A – Additional Drugs to be avoided in CLQTS WHICH are not included in first 3 categories
&search=drug.risk_category:P
rxnorm_id RxNorm Identification Number Any valid RxNorm ID &search=drug.rxnorm_id:3288

* Depending on your contract, you may not have access to this data-point.

Filter Data Fields

In order to limit result information, the filter query parameter can be used for any of the following data fields:

Data Field Description
generic_name Generic Name: Name of the unique medicine as defined by US Adopted Names (USAN) or the International Nonproprietary Name (INN)
link * Link (PubMed):  Link to the National Library of Medicine’s PubMed website to search for scientific articles that report QT prolongation or Torsades de pointes associated with the drug
class * Drug Class:  The drug class is the Anatomical Therapeutic Chemical (ATC) classification that is based on the drug’s predominant pharmacologic actions
tdp_risk_category Risk Category:  This field is the drug’s risk category for a drugs likelihood to cause Torsades de Pointes
brand Brand Names:  This field contains the names of the most commonly used brands of products that contain the medicine.  For some drugs, it is not a complete list.
administration_route * Administration Route:  The field includes a list of all of the routes of administration for which the drug has a risk associated with Torsades de Pointes
therapeutic_use * This field includes the predominant medical use(s) for the medication
atc_code * Anatomical Therapeutic Chemical (ATC) classification system: 5th level
rxnorm_id * RxNorm provides normalized names for clinical drugs and links its names to many of the drug vocabularies commonly used in pharmacy management and drug interaction software.
drugs_listed_in_contraindications_section * Contraindicated Concomitant medicines
warning_for_clqts * Warning for use in patients with congenital LQTS
ecg_recommendations_in_fda_label * ECG Recommendations in FDA label
market_status * List if drug is on US or Non-US markets or if it has been discontinued
qt_increase_mentioned_in_drug_label_y/n * QT increase mentioned in drug label
tdp_cases_mentioned_in_drug_label_y/n * TdP cases mentioned in drug label

* Depending on your contract, you may not have access to this data-point.

Result Format

The API returns results as JSON by default.

Section Description
Meta Metadata about the query, including a disclaimer, link to data license, last-updated date, and total matching records, if applicable.
Results List of matching results, dependent on which endpoint was queried.

Example Result

{ 
	"Meta": 
{ 
	"Disclaimer": "The absence of drugs from these lists should not be considered an indication that they are free of risk of QT prolongation or torsades de pointes. Many medicines have not been tested for this risk in patients, especially those with congenital long QT syndrome. All brand names may not be listed.", 
	"Last List Update": "June 15, 2016"
 }
, 
	"Results": [ 

{ 
	"generic_name": "Ritonavir", 
	"link": "http://www.ncbi.nlm.nih.gov/pubmed/?term=ritonavir+AND+(%22QT%22+OR+Torsad*)", 
	"class": "Antiviral", 
	"tdp_risk_category": "C", 
	"brand": "Norvir®", 
	"date_modified": "2014-11-11", 
	"administration_route": "oral", 
	"therapeutic_use": "Viral infection (HIV/AIDS)", 
	"atc_code": "J05AX66"
 }
 ]

 }

Examples

Example 1:

https://api.crediblemeds.org/index.php/tools/json?api_key={your_api_key}&search=list:dta&skip=10&limit=20&filter=generic_name+brand

Description:

  • Search parameters: list:dta - return Drugs to avoid list
 

Aditional Query parameters:

  • skip=10 - skip first 10 results
  • limit=20 – return 20 list elements
  • filter=Generic_Name+BrandNames – output "Generic_name" and "BrandNames" values
  • api_key = your API key (e.g "8cb34de5f2025cdc171a1b1fbea119bd")

 

Example 2:

https://api.crediblemeds.org/index.php/tools/json?api_key={your_api_key}&search=drug.risk_category:A+[AND]+drug.therapeutic_use:obesity

Description:

  • Search parameters: Return drugs which match both conditions: risk category = A AND therapeutic use contain keyword "obesity"
 

Aditional Query parameters, ff not set, by default additional query parameters are set:

  • limit = ∞
  • skip = 0
  • filter = return all drug fields

Example 3:

https://api.crediblemeds.org/index.php/tools/json?api_key={your_api_key}&search=drug.risk_category:A+drug.therapeutic_use:obesity

Description:

  • Search parameters: Return drugs which match condition: risk category = A OR therapeutic use contain keyword "obesity"





If you need further help with the implementation, please connect with us to schedule a meeting.