Example

In this example we will be downloading in CSV format the mean systolic blood pressure from all male patients in the NHANES database.

NOTE:
All commands are run against the https://nhanes.hms.harvard.edu e.g. https://nhanes.hms.harvard.edu/rest/v1/queryService/runQuery

Step Command
Get the BD2K PIC-SURE API Token Go to nhanes.hms.harvard.edu, and click the Public User button on the top right, and then the User Profile from the dropdown menu.
The UserProfile page contains a "Token" tab, where you will find a unique token, which is required to access the PIC-SURE API. Copy this long string onto your clipboard.

On a UNIX system, create an environment variable, NHANES_TOKEN and store the value of the token in that variable (it will be used in the below examples.)

export NHANES_TOKEN="eyJ0eXAiOiJKV ... HZq4D7JnvFJE"
Test that you have access to the PIC-SURE API (optional) cURL
curl -H "Authorization: Bearer ${NHANES_TOKEN}" \
  "http://nhanes.hms.harvard.edu/rest/v1/systemService/about"


HTTP_RESPONSE:
{ "app": "1.4.2", ... "user": { "email":"<VALID_EMAIL_ADDRESS>" } }

Run a Query cURL:
curl -H "Authorization: Bearer ${NHANES_TOKEN}" \
   --data @query.json \
  "http://nhanes.hms.harvard.edu/rest/v1/queryService/runQuery"


where the query.json file contains the following query:
{
  "select": [
      {
        "field": {
          "pui": "/nhanes/Demo/examination/examination/blood pressure/mean systolic/",
          "dataType": "STRING"
        },
        "alias": "Systolic Pressure"
      }
  ],
  "where": [
      {
        "field": {
          "pui": "/nhanes/Demo/demographics/demographics/SEX/male",
          "dataType": "STRING"
        },
        "predicate": "CONTAINS",
        "fields": {
          "ENCOUNTER": "YES"
        }
      }
  ]
}
HTTP_RESPONSE:
{ "resultId": 22449 }
Check the status of the result Use the previously returned resultId, to check the status.

cURL
curl -H "Authorization: Bearer ${NHANES_TOKEN}" \
http://nhanes.hms.harvard.edu/rest/v1/resultService/resultStatus/22449


HTTP_RESPONSE:
{ "resultId": 22449, "status": "AVAILABLE" }

Other options for status value are RUNNING or ERROR

Check the available formats for the result cURL:
curl -H "Authorization: Bearer ${NHANES_TOKEN}" \
/rest/v1/resultService/availableFormats/22449


HTTP_RESPONSE:
[ "JSON", "XML", "XLSX", "CSV" ]
Download the results as a CSV cURL:
curl -H "Authorization: Bearer ${NHANES_TOKEN}" \
http://nhanes.hms.harvard.edu/rest/v1/resultService/result/22449/CSV?download=yes


HTTP_RESPONSE:
# File should be downloaded to your computer.