AndWellness-JSON

From CSL Wiki

(Difference between revisions)

Revision as of 18:09, 4 November 2009

1 HTTP Between Phone and Server
2 JSON

HTTP Between Phone and Server

This page defines the data format (schema) used between a phone and the server application. The client-server protocol uses JSON over HTTP. It is expected that the schema will change over time. The upload URL will be something like http://pilot.andwellness.cens.ucla.edu/upload?json={...}. TBC.

All client-server communication must use UTF-8 character encoding.

JSON

Naming Conventions

All keys use lowercase.
All multi-word keys use dashes as a word separator.
All multi-word values use underscores as a word separator.

Upload Format

phone-version: A float representing the phone application version. Required. Usage TBD.
protocol-version: A float representing the JSON protocol version the current message adheres to. Required. Usage TBD.
data: An array of objects. At least one packet is required and 500 is the maximum.

   {
      "phone-version":0.1,
      "protocol-version":0.1,
      "data":[first packet],[second packet], ... ,[nth packet]
   }

Data Packet

The data packet is a JSON Object with a set of standard and function-specific data elements.

user-name: A string used for identification. Required.
date: A string in the ISO 8601 format to the detail of seconds “YYYY-MM-DD hh:mm:ss”. Required.
time: An int specifying the number of milliseconds since the epoch.
type: A lowercase string specifying the data type. Required.
sub-type: A lowercase string specifying the data subtype (specialization). Required.
latitude: A float representing latitude. Required.
longitude: A float representing latitude. Required.
time-zone: A string representing a standard time zone. Required.
Feature specific data.

Example:

   [{
       "user-name":"bob@example.com",
       "date":"2009-11-03 10:18:33",
       "time":1257272467077,
       "type":"type",
       "sub-type":"subtype",
       "latitude":38.8977,
       "longitude",-77.0366,
       "time-zone":"EST",
       ...
   }]

Message Types and Subtypes

Each JSON message has a type and a subtype. The reason we have introduced typing into the message protocol is due to the nature of having only one upload URL (API entry point). If we had separate URLs for say, mobility uploads and prompt responses, we could remove one level of typing from these messages. It would be nice for AndWellness to have multiple URLs as described, but for the PDV, separate URLs would be a difficult task due to the PDV's generic nature of being able to interface with many third-party applications and datatypes.

Mobility Types and Subtypes

The mobility type allows us to specify details for messages related to the phone user's mobility state.

The mobility subtypes are: mode_only and mode_features. Each subtype specifies a data packet as described below.

type: mobility
- subtype: mode_only
  - mode: A lowercase string specifying an mobility mode. The allowed values are: still, walk, run, bike, drive. Required.

type: mobility
- subtype: mode_features
  - features An object specifying classification features. Required.
    - speed A float. Required.
    - variance: A float. Required.
    - average: A float. Required.
    - fft: An array of ten floats. Required.

Example (type=mobility, subtype=mode_only):

   [{
       "user-name":"bob@example.com",
       "date":"2009-11-03 10:18:33",
       "time":1257272467077,
       "type":"mobility",
       "sub-type":"mode_only",
       "latitude":38.8977,
       "longitude",-77.0366,
       "time-zone":"EST",
       "mode":"still"
   }]

Example (type=mobility, subtype=mode_features):

   [{
       "user-name":"bob@example.com",
       "date":"2009-11-03 10:18:33",
       "time":1257272467077,
       "type":"mobility",
       "sub-type":"mode_features",
       "latitude":38.8977,
       "longitude",-77.0366,
       "time-zone":"EST",
       "features":{
           "speed":0.0,
           "variance":0.0,
           "average":0.0,
           "fft":[0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0]
       }
   }]

Prompt Types and Subtypes

The prompt type allows us to specify details for messages related to the phone user's EMA responses. Each prompt type message must contain a subtype. For the initial rollout of the application, the server will be accepting responses for five different prompts: stress, mood, energy, glucose level, and blood pressure. Stress, mood, energy, and glucose level have range-bound values while blood pressure has values for systolic and diastolic pressure.

Prompt	Response Limits
Stress	1 <= n <= 5
Mood	1 <= n <= 5
Energy	1 <= n <= 5
Glucose Level	1 <= n <= 11
Blood Pressure	Two integer values: systolic and diastolic pressure. Min and max for each TBD.

Message hierarchy:

type: prompt
- subtype: a lowercase string that is one of: stress, mood, energy, bloodpressure
  - response: any JSON object (the format of the response depends on the subtype)

Example (type=prompt, subtype=stress)

   [{
       "user-name":"bob@example.com",
       "date":"2009-11-03 10:18:33",
       "time":1257272467077,
       "type":"prompt",
       "sub-type":"stress",
       "latitude":38.8977,
       "longitude",-77.0366,
       "time-zone":"EST",
       "response":1
   }]

Example (type=prompt, subtype=mood)

   [{
       "user-name":"bob@example.com",
       "date":"2009-11-03 10:18:33",
       "time":1257272467077,
       "type":"prompt",
       "sub-type":"mood",
       "latitude":38.8977,
       "longitude",-77.0366,
       "time-zone":"EST",
       "response":1
   }]

Example (type=prompt, subtype=energy)

   [{
       "user-name":"bob@example.com",
       "date":"2009-11-03 10:18:33",
       "time":1257272467077,
       "type":"prompt",
       "sub-type":"energy",
       "latitude":38.8977,
       "longitude",-77.0366,
       "time-zone":"EST",
       "response":1
   }]

Example (type=prompt, subtype=glucose_level)

   [{
       "user-name":"bob@example.com",
       "date":"2009-11-03 10:18:33",
       "time":1257272467077,
       "type":"prompt",
       "sub-type":"glucose_level",
       "latitude":38.8977,
       "longitude",-77.0366,
       "time-zone":"EST",
       "response":1
   }]

Example (type=prompt, subtype=blood_pressure)

   [{
       "user-name":"bob@example.com",
       "date":"2009-11-03 10:18:33",
       "time":1257272467077,
       "type":"prompt",
       "sub-type":"blood_pressure",
       "latitude":38.8977,
       "longitude",-77.0366,
       "time-zone":"EST",
       "response":{
           "systolic":70,
           "diastolic":100
       }
   }]

Prompts/EMAs we are considering for future iterations of the application are: diet, exercise, sexual interactions, drug use, and various biomarkers. It would be good to separate the EMAs by proposal. TBD.

Retrieved from "http://www.lecs.cs.ucla.edu/wiki/index.php/AndWellness-JSON"

AndWellness-JSON

From CSL Wiki

Revision as of 18:09, 4 November 2009

Contents

HTTP Between Phone and Server

JSON

Naming Conventions

Upload Format

Data Packet

Message Types and Subtypes

Mobility Types and Subtypes

Prompt Types and Subtypes

Views

Personal tools

Navigation

Search

Toolbox