En español
NIDA

Developers API

Revised October 2012

Description

To get all questions, its sub questions, options, next rule and the final result calculation rule.

URL: <URLBASE>/get_all_questions

Logic

All the questions, sub questions, options, question rule and the final result rule are retrieved from data base and they are returned in JSON format.

Sample Request Format
{
    "key": "qtye456ceger",
    "questionnaire_type" : "2"
}

Params 

questionnaire_type optional. Take values 1 or 2.Default is 1 unless specified
 


Method 

(GET|POST)

Sample Response of Questionnaire Type 1

{
  "status": "1",
  "messages": [
    {
      "message": "Success using API"
    }
  ],
  "questions": [
    {
      "question_id": 1,
      "description": "In the past year, how often have you used the following?",
      "comment": null,
      "sub_questions": [
        {
          "name": "Alcohol",
          "question_id": 1,
          "sub_question_id": 1,
          "description":"For men, 5 or more drinks a day. For women, 4 or more drinks a day"	
        },
        {
          "name": "Tobacco Products",
          "question_id": 1,
          "sub_question_id": 2
        },
        {
          "name": "Prescription Drugs for Non-Medical Reasons",
          "question_id": 1,
          "sub_question_id": 3
        },
        {
          "name": "Illegal Drugs",
          "question_id": 1,
          "sub_question_id": 4
        }
      ],
      "options": [
        {
          "name": "Never",
          "option_id": 1,
          "option_value": 0,
          "question_id": 1
        },
        {
          "name": "Once or Twice",
          "option_id": 2,
          "option_value": 1,
          "question_id": 1
        },
        {
          "name": "Monthly",
          "option_id": 3,
          "option_value": 1,
          "question_id": 1
        },
        {
          "name": "Weekly",
          "option_id": 4,
          "option_value": 1,
          "question_id": 1
        },
        {
          "name": "Daily or Almost Daily",
          "option_id": 5,
          "option_value": 1,
          "question_id": 1
        }
      ],
      "rules": [
        {
          "order": 1,
          "left_operand": "sq_1",
          "operator": ">",
          "right_operand": "0",
          "success": {
            "message": "Patient is an at-risk drinker.One or more days of heavy drinking (e.g. drinking more than the amounts shown in the previous screen for men or women) places a patient at risk.",
            "more_info_link": "http://pubs.niaaa.nih.gov/publications/Practitioner/CliniciansGuide2005/clinicians_guide.htm",
            "more_info_text": "Please see 'Helping Patients Who Drink Too Much: A Clinician's Guide' for information to help assess, advise, and assist at-risk drinkers or patients with alcohol use disorders."
          }
        },
        {
          "order": 2,
          "left_operand": "sq_2",
          "operator": ">",
          "right_operand": "0",
          "success": {
            "message": "Any current tobacco use places a patient at risk. Advise all tobacco users to quit.",
            "more_info_link": "http://www.ahrq.govclinic/tobacco/clinhlpsmksqt.htm",
            "more_info_text": "For more information on smoking cessation, please see 'Helping Smokers Quit: A Guide for Clinicians.'"
          }
        },
        {
          "order": 3,
          "left_operand": "sq_3",
          "operator": ">",
          "right_operand": "0",
          "success": {
            "next_question_id": "2"
          }
        },
        {
          "order": 4,
          "left_operand": "sq_4",
          "operator": ">",
          "right_operand": "0",
          "success": {
            "next_question_id": "2"
          }
        },
        {
          "order": 5,
          "left_operand": "q_sum_all",
          "operator": "==",
          "right_operand": "0",
          "success": {
            "message": "Reinforce absistence. Screening is complete."
          }
        }
      ]
    },
    {
       //Another question body

    },
    .
    .
    .
  ],

   "result_rules": [
    {
      "left_operand": "sum",
      "operator": ">",
      "right_operand": 26,
      "success": {
        "message": "High Risk"
      }
    },
    {
      "left_operand": "sum",
      "operator": ">",
      "right_operand": 3,
      "success": {
        "message": "Moderate Risk"
      }
    },
    {
      "left_operand": "sum",
      "operator": ">",
      "right_operand": -1,
      "success": {
        "message": "Low Risk"
      }
    }
  ]
}     

Response fields

status Status of the API request
errors Errors if any
messages Messages if any
questions An array which include all the questions, sub questions, options and its next rules.
question_id To identify each question 
sub_questions An array which include all the sub questions of the question. Each sub question has a sub_question_id, name and question_id.
options An array which includes option_id, its name, value and question_id as its fields
rules An array which include limited number of rules. Each rule has an order, left_operand, operator, right_operand and a success.
result_rules An array which include limited number of rules. Each rule has a left_operand, operator, right_operand and a success message.

Sample Response of Questionnaire Type 2

{ "status": "1",
  "questionnaire_type": "2",
  "messages": [
    {
      "message": "Success using API"    }
    ],
  "questions": [
    {
      "question_id": 1,
      "description": "In the past year, how often have you used the following?",
      "comment": null,
      "sub_questions": [
        {
          "sub_question_id": 1,
          "name": "Alcohol(For men, 5 or more drinks a day.For women, 4 or more drinks a day)",
          "question_id": 1,
          "options": [
            {
              "name": "Never",
              "option_id": 1,
              "option_value": 0,
              "question_id": 1
            },
            {
              "name": "Once or Twice",
              "option_id": 2,
              "option_value": 1,
              "question_id": 1
            }
          ]
        },
        {
         //Another sub_question
        }
        .
        .
        .
      ],
      "rules": [
        {
          "order": 1,
          "left_operand": "sq_1",
          "operator": ">",
          "right_operand": "0",
          "success": {
            "message": "Patient is an at-risk drinker.One or more days of heavy drinking (e.g. drinking more than the amounts shown in the previous screen for men or women) places a patient at risk.",
            "more_info_link": "http://pubs.niaaa.nih.gov/publications/Practitioner/CliniciansGuide2005/clinicians_guide.htm",
            "more_info_text": "Please see 'Helping Patients Who Drink Too Much: A Clinician's Guide' for information to help assess, advise, and assist at-risk drinkers or patients with alcohol use disorders."
          }
        },
        {
          "order": 2,
          "left_operand": "sq_2",
          "operator": ">",
          "right_operand": "0",
          "success": {
            "message": "Any current tobacco use places a patient at risk. Advise all tobacco users to quit.",
            "more_info_link": "http://www.ahrq.gov/clinic/tobacco/clinhlpsmksqt.htm",
            "more_info_text": "For more information on smoking cessation, please see 'Helping Smokers Quit: A Guide for Clinicians.'"
          }
        }
      ]
    },
    {
      "question_id": 2,
      "description": "In your LIFETIME, which of the following substances have you ever used?",
      "comment": "*Note for Physicians: For prescription medications, please report nonmedical use only.",
      "sub_questions": [
        {
          "sub_question_id": 5,
          "name": "Cannabis",
          "question_id": 2,
          "options": [
            {
              "name": "No",
              "option_id": 7,
              "option_value": 0,
              "question_id": 2
            },
            {
              "name": "Yes",
              "option_id": 6,
              "option_value": 1,
              "question_id": 2
            }
          ],
          "description":"marijuana, pot, grass, hash, etc."
        },
        {
          "sub_question_id": 6,
          "name": "Cocaine",
          "question_id": 2,
          "options": [
            {
              "name": "No",
              "option_id": 7,
              "option_value": 0,
              "question_id": 2
            },
            {
              "name": "Yes",
              "option_id": 6,
              "option_value": 1,
              "question_id": 2
            }
          ],
          "description":"coke, crack, etc."
        },
        .
        .
        .
        .      
        {
          "sub_question_id": 13,
          "name": "Prescription opioids",
          "question_id": 2,
          "options": [
            {
              "name": "No",
              "option_id": 7,
              "option_value": 0,
              "question_id": 2
            },
            {
              "name": "Yes",
              "option_id": 6,
              "option_value": 1,
              "question_id": 2
            }
          ],
          "description":"fentanyl, oxycodone[OxyContin, Percocet], hydrocodone[Vicodin], methadone, buprenorphine, etc."
        }
      ],
      "rules": [
             // Rules of question_id 2
      ]
    },
    {
      "question_id": 3,
      "name":"Cannabis",
	  "description":"marijuana, pot, grass, hash, etc.",
      "comment": null,
      "sub_questions": [
          // sub_questions of question_id 3
      ],
      "rules": [
         // Rules of question_id 3
      ]
    }
  ],
  "result_rules": [
    {
      "order": 1,
      "left_operand": "sum",
      "operator": ">",
      "right_operand": 26,
      "success": {
        "message": "High Risk"
      }
    },
    {
      "order": 2,
      "left_operand": "sum",
      "operator": ">",
      "right_operand": 3,
      "success": {
        "message": "Moderate Risk"
      }
    },
    {
      "order": 3,
      "left_operand": "sum",
      "operator": ">",
      "right_operand": -1,
      "success": {
        "message": "Low Risk"
      }
    }
  ]
}
Response fields
status Status of the API request
errors Errors if any
messages Messages if any
questions An array which include all the questions, sub questions, options and its next rules.
question_id To identify each question 
sub_questions An array which include all the sub questions of the question. Each sub question has a sub_question_id, name and question_id.
options An array which includes option_id, its name, value and question_id as its fields
rules An array which include limited number of rules. Each rule has an order, left_operand, operator, right_operand and a success.
result_rules An array which include limited number of rules. Each rule has a left_operand, operator, right_operand and a success message.
 
How to evaluate rules
 
Each question may have set of rules. In addition to the question rule the response includes a set of rules to find the result of each sub question.
 
Question rules

 

Each rule have a left_operand, operator, right_operand, order and a success.

 

  • left_operand will be either one of the following:
  • q_sum_all : Sum of selected option values of all the sub questions in the current question.
  • sq_1 : Option value of the first sub question in the current question.
  • sq_2 : Option value of the second sub question in the current question.
  • sq_3 : Option value of the third sub question in the current question.
  • sq_4 : Option value of the fourth sub question in the current question.
  • q_2_sq_1: Option value of first sub question of question id 2.
  • q_2_sq_2: Option value of second sub question of question id 2 and so on.
  • operator will be either one of the following:
  • >
  • <
  • ==
  • right_operand will be any integer.
  • Each rule will be evaluated one by one as per the order.
  • success will have any one or two of the following:
  • message
  • more_info_text and more_info_link
  • next_question_id
Substitute the value of left_operand and evaluate the rule . If it returns false evaluate next rule and if it returns true, following should be considered:
  • If the success has a message part then the message should be prompted to the user.
  • if the success has a more_info_text and more_info_link then the link with the text should be prompted to the user.
  • If the success has a next_question_id then go to the next question of the corresponding question_id
Result rules
 
Each rule in result rules have a left_operand, operator, right_operand and a success. The result should be calculated for each sub question which marked 'Yes' in the second question.
  • left_operand should be either the sum of the scores of each sub question from question 3 to 8 of questionnaire type1 or the sum of scores of each of the questions from question 3 to 11 of  questionnaire type 2.
  • operator will be either one of the following:
  • >
  • <
  • ==
  • right_operand will be any integer.
  • Each rule will be evaluated one by one as per the order.
  • success will have a message.
When evaluating, if any of them returns true the message is prompted to the user for the corresponding sub question and should ignore the following rules for the corresponding sub question.

 

This page was last updated October 2012