Overview

This document describes the standard APIs that exist for access to the AtoZ data. For each API, the document describes input parameters required when calling the API and the returned data that the API will produce. All APIs are RESTful HTTP(S) interactions that return an HTTP header status code and a JSON data-structure with the payload of the response to the API. Before calling any of the clinical data APIs the external application must first call the “getToken” API to obtain an “access token”. This token is used as one of the input parameters to all subsequent API interactions. The token is essentially an authentication and licensing artefact. Depending on your licensing agreement with AtoZ the token could be time-limited. If a token expires you will need to call the getToken API again to obtain a fresh token. The authentication token must be passed to all subsequent API calls as an HTTP header or as GET or POST values. Best practice is to use the HTTP header mechanism as the token is then not held by any proxy servers on the network path. For testing purposes please use the username TESTING with password API-TEST. This will give you access to the fully functional API set, but with a limited number of medicines. The medicines available using the test account are detailed in Appendix A of this document. Upon completion of contractual agreements a dedicated user account (or accounts) will be allocated, which are not restricted to the test set of medicines. The base URL for all API calls is https://api.atozofmedicines.com/app Where any of the APIs return an empty result, the output will simply be the JSON encoded string “NO RESULT”

Pregnancy

Request

/api.json/Pregnancy

HTTP Header

  • Token – a valid token obtained through a successful call to the getToken API
Input Parameters
  • tok – a valid token obtained through a successful call to the getToken API.  Only use this input parameter if you have NOT used the Token HTTP header mechanism.
  • lst – a single or pipe-delimited list of medicine ID’s or NAPPI(6) codes
  • lang – Optional. The target language for output. Defaults to CHW-EN=Community Health Worker English (English lay translation).  Contact AtoZ for other options.
  • useKey – Optional, defaults to “Y”. Indicates if “lst” comprises a list of medicines that were identified by calling the AtoZ “searchTrade API (i.e. are a set of primary keys to the AtoZ database). Values are “Y” for yes, and “N” for no.  
  • useCode – optional, defaults to “Y”. Indicates if “lst” comprises a list of medicines that are identified by a national coding system (e.g. a list of NAPPI codes, NDC codes etc.), Values are “Y” for yes, and “N” for no.
Response
HTTP Status Response Meaning
200 {

  “DATA”: [

  {

    “DriverID”: “161493”,

    “Wording”: “Dangerous. Major problems caused in babies. Do not use unless told to by a doctor.  Women taking this drug should not fall pregnant and should use reliable contraception.”,

    “Icon”: “unsafe.png”

  }

],

 “MESSAGE”: {

    “NoData”: [

      [“1234”], [ “5678” ]

    ]

  }

}

Success.  A JSON array, containing a “DATA” section and a “MESSAGE” section.

The “DATA” section comprises:
DriverID – the medicine ID for the item in question
Wording – the wording to display as the pregnancy risk for this medicine ID
Icon – an optional icon indicator to use when displaying this wording

The “MESSAGE” section comprises an array of “NoData” nodes representing codes for which no data was available.

401 Unauthorised – the token is invalid
406 Not Acceptable – you are using POST, DELETE for PUT where an HTTP GET command is expected

Lactation

Request

/api.json/Lactation

HTTP Header
  • Token – a valid token obtained through a successful call to the getToken API
Input Parameters
  • tok – a valid token obtained through a successful call to the getToken API.  Only use this input parameter if you have NOT used the Token HTTP header mechanism.
  • lst – a single or pipe-delimited list of medicine ID’s or NAPPI(6) codes
  • lang – Optional. Target language for output. Defaults to CHW-EN=Community Healthworker English (lay translation).  Contact AtoZ for other options.
  • useKey – Optional, defaults to “Y”. Indicates if “lst” comprises a list of medicines that were identified by calling the AtoZ “searchTrade API (i.e. are a set of primary keys to the AtoZ database). Values are “Y” for yes, and “N” for no.  
  • useCode – optional, defaults to “Y”. Indicates if “lst” comprises a list of medicines that are identified by a national coding system (e.g. a list of NAPPI codes, NDC codes etc.), Values are “Y” for yes, and “N” for no.
Response
HTTP Status Response Meaning
200 {“DATA”:

[{
“DriverID”:”110332″,

“Name”:”Zocor”,

“Risk”:”x”,

“Icon”:”skull.png”,

“ATC_Description”:”Simvastatin”,

“Wording”:”Avoid. Substitute a safer alternative.”,

“ReferenceID”:”4433″,

“Details”:””

}],

“MESSAGE”:{“NoData”:””}}

Success.  A JSON array, containing a “DATA” section and a “MESSAGE” section.  

The “DATA” section comprises:
DriverID – the medicine ID for the item in question
Wording – the wording to display as the lactation risk for this medicine ID
Icon – an optional icon indicator to use when displaying this wording

The “MESSAGE” section comprises an array of “NoData” nodes representing codes for which no data was available.

401 Unauthorised – the token is invalid
406 Not Acceptable – you are using POST, DELETE for PUT where an HTTP GET command is expected

Porphyria

Request

/api.json/Porphyria

HTTP Header
  • Token – a valid token obtained through a successful call to the getToken API
Input Parameters
  • tok – a valid token obtained through a successful call to the getToken API.  Only use this input parameter if you have NOT used the Token HTTP header mechanism.
  • lst – a single or pipe-delimited list of medicine ID’s or NAPPI(6) codes
  • useKey – Optional, defaults to “Y”. Indicates if “lst” comprises a list of medicines that were identified by calling the AtoZ “searchTrade API (i.e. are a set of primary keys to the AtoZ database). Values are “Y” for yes, and “N” for no.  
  • useCode – optional, defaults to “Y”. Indicates if “lst” comprises a list of medicines that are identified by a national coding system (e.g. a list of NAPPI codes, NDC codes etc.), Values are “Y” for yes, and “N” for no.
Response
HTTP Status Response Meaning
200 {“DATA”:

[{

“DriverID”:”110332″,

“Name”:”Zocor”,

“Risk”:”Avoid.”,

“Wording”:”Avoid.”,

“Icon”:”skull.png”,

“ATC_Description”:”Simvastatin”,

“ReferenceID”:”3380″

}],

“MESSAGE”:{“NoData”:””}}

Success.  A JSON array, containing a “DATA” section and a “MESSAGE” section.  

The “DATA” section comprises:
DriverID – the medicine ID for the item in question
Wording – the wording to display as the porphyria risk for this medicine ID
Icon – an optional icon indicator to use when displaying this wording

The “MESSAGE” section comprises an array of “NoData” nodes representing codes for which no data was available.

401 Unauthorised – the token is invalid
406 Not Acceptable – you are using POST, DELETE for PUT where an HTTP GET command is expected

Interactions

Request

/api.json/Interactions

HTTP Header
  • Token – a valid token obtained through a successful call to the getToken API
Input Parameters
  • tok – a valid token obtained through a successful call to the getToken API.  Only use this input parameter if you have NOT used the Token HTTP header mechanism.
  • lst – a pipe-delimited list of medicine ID’s as returned by the searchTrade API (or a pipe-delimited list of 6/7 digit NAPPI codes)
  • useKey – Optional, defaults to “Y”. Indicates if “lst” comprises a list of medicines that were identified by calling the AtoZ “searchTrade API (i.e. are a set of primary keys to the AtoZ database). Values are “Y” for yes, and “N” for no.  
  • useCode – optional, defaults to “Y”. Indicates if “lst” comprises a list of medicines that are identified by a national coding system (e.g. a list of NAPPI codes, NDC codes etc.), Values are “Y” for yes, and “N” for no.
Response
HTTP Status Response Meaning
200 {

  “DATA”: [

    {

      “TradeA”: “110332”,

      “MedicineA”: “Zocor”,

      “TradeB”: “119234”,

      “MedicineB”: “Cipla Warfarin”,

      “severity”: “unsafe.png”,

      “SeverityRank”: “2”,

      “Details”: {

        “Detail1”: {

          “Category”: “Warning”,

          “Description”: “Caution advised.”,

          “ReferenceID”: “24675”

        },

      “References”: [“…”, “…”]

      }

    }

  ],

  “MESSAGE”: {

    “NoData”: [

      [“1234”], [“5678”]

    ]

  }

}

Success.  A JSON array, containing a “DATA” section and a “MESSAGE” section.

The “DATA” section comprises:
TradeA – the medicine ID for one of the item in question
TradeB – the medicine ID for another of the item in question, which interacts with TradeA
MedicineA – the name of the one medicine in question
MedicineB – the name of the other medicine in question
severity and SeverityRank – see appendix B for details.
Details – An array of details where each detail contains ‘Category‘, ‘Description‘ & ‘ReferenceID‘.  See appendix B for details
References – An array strings where each string is a fully qualified reference to the journals and publications that give rise to this interaction’s data.

The “MESSAGE” section comprises an array of “NoData” nodes representing codes for which no data was available.

401 Unauthorised – the token is invalid
406 Not Acceptable – you are using POST, DELETE for PUT where an HTTP GET command is expected

Provider Single Drug Lookup

Request

/api.json/ProviderSDL

HTTP Header
  • Token – a valid token obtained through a successful call to the getToken API
Input Parameters
  • tok – a valid token obtained through a successful call to the getToken API.  Only use this input parameter if you have NOT used the Token HTTP header mechanism.
  • lst – The identifier of the medicine in question. Use ID returned by the searchTrade API, or a South African NAPPI code.  To use an American NDC code please ensure you use one of the “USA…” translation languages in the translation field (see field “lang” below).
  • lang – The required “language” for the output.  Leave this blank to use standard terminology for medical providers.  Use “ENG-LAY” for lay translations in English.  Use “USA-LAY” or “USA-Dr” to force American drug coding (NDC codes) for the medicine identifier.
Response
HTTP Status Response Meaning
200 {

  “DATA”: {

    “AMI Name”: [],

    “Trade Name”: [],

    “Trade Names List”: [],

    “Therapeutic class”: [],

    “Pharmacological class”: [],

    “AMI Description and general information”: [],

    “AMI 2D image of structure”: [],

    “Molecular formula”: [],

    “Molecular weight”: [],

    “Warning Black box*”: [],

    “Contraindicated in”: [],

    “Avoid in”: [],

    “Caution in”: [],

    “Allergy\/ cross sensitivity interaction”: [],

    “Warning”: [],

    “Side effects in precautions”: [],

    “Monitor patient for signs or symptoms of”: [],

    “Dose advice”: [],

    “Drug interactions”: [],

    “Side effects”: []

  },

  “MESSAGE”: {

    “NoData”: “”

  }

}

Success.  A JSON array, containing a “DATA” section and a “MESSAGE” section.


The “DATA” section comprises sub-arrays with details for each of the various sections as indicated on the left. 

The “MESSAGE” section contains the “lst” value if no data was found matching the code used as the input parameter.

401 Unauthorised – the token is invalid
406 Not Acceptable – you are using POST, DELETE for PUT where an HTTP GET command is expected

Patient Single Drug Lookup

Request

/api.json/PatientSDL

HTTP Header
  • Token – a valid token obtained through a successful call to the getToken API
Input Parameters
  • tok – a valid token obtained through a successful call to the getToken API.  Only use this input parameter if you have NOT used the Token HTTP header mechanism
  • lst – The identifier of the medicine in question. Use an ID returned by the searchTrade API, or a South African NAPPI code.  To use an American NDC code please ensure you use one of the “USA…” translation languages in the translation field (see field “lang” below).
  • lang – The required “language” for the output.  Leave this blank to use standard terminology for medical providers.  Use “ENG-LAY” for lay translations in English.  Use “USA-LAY” or “USA-Dr” to force American drug coding (NDC codes) for the medicine identifier.
Response
HTTP Status Response Meaning
200

    “DATA”: { 

        “Active ingredient”: [], 

        “Pharmacological class”: [], 

        “Before using”: [], 

        “Drug Interactions”: [], 

        “Side effects”: [], 

        “Notify if”: [], 

        “Important info”: [] 

    }, 

    “MESSAGE”: { 

        “NoData”: “” 

    } 

}

Success.  A JSON array, containing a “DATA” section and a “MESSAGE” section.


The “DATA” section comprises sub-arrays with details for each of the various sections as indicated on the left. 

The “MESSAGE” section contains the “lst” value if no data was found matching the code used as the input parameter.

401 Unauthorised – the token is invalid
406 Not Acceptable – you are using POST, DELETE for PUT where an HTTP GET command is expected

Appendix A – Test Medicines

For testing purposes please use the test username (TESTING) and password (API-TEST).

This will give you access to all medicine trade names in South Africa, the following medicine groups:

  • Cefotaxime
  • Amlodipine
  • Amoxicillin
  • Atosiban
  • Clarithromycin
  • Deferasirox
  • Enoxaparin
  • Folic acid
  • Clindamycin
  • Omeprazole
  • Ciprofloxacin
  • Oxycodone
  • Paracetamol
  • Phenytoin
  • Simvastatin
  • Warfarin

Appendix B – Clinical Details

The Drug Interaction API
Severity levels 

Our risk rating categories for the drug interaction API order the interaction output.

Interactions are ranked with a severity from 1 to 6 in order of decreasing severity as shown below.

 

Severity
Rank
Icon Colour Wording Description
1 skull.png Black Contraindicated This combination of medicines is considered to be contraindicated. This combination may be life-threatening or fatal. The risks associated with this combination outweigh the benefits.
2 unsafe.png Red Avoid This combination of medicines should be avoided as potential risks outweigh the benefits. Significant adverse effects are possible. Close patient monitoring and/or dose adjustment and/or substitution is recommended if this combination is used.
3 caution.png Orange Caution This combination of medicines should be used with caution and only if the benefit outweighs the risk. Adverse effects are possible. The patient should be monitored and dose adjustments made where necessary.
4 note.png Yellow Theoretical risk A theoretical risk of an interaction exists. Adverse outcomes appear to be insignificant.
5 safe.png Green Low risk No clinically significant interaction expected or no interaction documented.
6 info.png Grey Information Information unrelated to severity e.g. antidote information.

 

The first three categories require action or monitoring with the caveat that, as a result of inter-patient variability (pharmacogenomics), not all patients will experience a drug interaction in the same way.  In many cases the interactions are delayed and may only be seen on stopping one or other drug in the interaction basket in question.  

The last three categories are considered to be theoretical or of little or no clinical significance. 

Categories of information

Our information is categorized as below.  Not all interactions have data in every single category. Where we have captured referenced data these will output in the following order:

Rank Wording Description
1 Warning Overall risk rating of the combination.
2 Note Additional information that may qualify or add to the understanding of the interaction.
3 Advice Advice on dose adjustment, substitution or cessation.
4 Monitor All information related to monitoring either the patient or the drug. This includes therapeutic drug monitoring and clinical monitoring for efficacy, toxicity or adverse effects.
5 Condition Where an interaction occurs when certain conditions apply e.g. renal impairment, high-dose, chronic use, or a sub-population such as the elderly.
6 Serum Effect of the combination on drug serum levels.
7 Outcome risks Adverse outcomes of the drug combination.
8 Mechanism Mechanism of action of the interaction.
9 Clinical significance The level of clinical significance of the interaction.
10 Evidence The level of clinical evidence pertaining to the interaction.
11 Counselling Patient counselling with respect to food, alcohol and important symptoms which, if experienced, should be reported to their doctor.