-
Notifications
You must be signed in to change notification settings - Fork 25
Survey Manipulation
Steve Nolen edited this page Mar 31, 2016
·
44 revisions
- Survey Upload
- Survey Response Read
- Survey Response Update Privacy State
- Survey Response Delete
- Survey Response Function Read
Allows survey responses for a particular campaign to be uploaded to the system. The content type must be multipart/form-data.
Media must be attached with a content type of <media_type>/<sub_type>, e.g. image/jpeg, video/mpeg, audio/mp3, etc..
survey/upload
Campaign participants may upload surveys if the campaign in question is running.
-
(r) user = The username of the participant taking the survey.
-
(r) password = The hashed password of the participant taking the survey (see: user/auth).
OR -
(r) auth_token = A previously generated, valid authentication token.
-
(r) client = A string representing the client.
-
(r) campaign_urn = A campaign URN.
-
(r) campaign_creation_timestamp = The creation timestamp of the campaign.
-
(r) surveys = A JSON array of data packets (See below for specification.)
-
(o) update = A boolean representing whether or not to use this data to update a survey response if one already matches the given survey uuid. Requires that the campaign_urn for the upload have its editable parameter set to true.
-
(o) private_state = One of ["private", "shared"]. Default per-server value is used if this value is not passed.
-
(r) images = A JSON object whose keys are the image's IDs and their respective values are the BASE64 encoding of the image's contents.
OR -
0...n attachments for the survey based on how many media responses are present in the data payload. Each media must be represented as an attached file where the filename must be the UUID contained the survey data JSON.
POST /app/survey/upload HTTP/1.1
Host: dev.ohmage.org
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
Content-Length: byte-length-of-content
Content-Type: application/x-www-form-urlencoded
user=test.user
&password=hashed_password
&client=android-4.0
&campaign_urn=urn:mobilize:sleep
&campaign_creation_timestamp=2012-01-01 08:00:00
&surveys=json_array
curl --trace-ascii ~/curltrace.txt -F "user=josh" -F "password=p" -F "client=curl" -F "campaign_urn=urn:mobilize:sleep" -F "campaign_creation_timestamp=2012-01-01 08:00:00" -F "[email protected];type=application/json" -F "[email protected];type=image/jpeg" http://localhost:8080/app/survey/upload
POST /app/survey/upload HTTP/1.1
Host: dev.ohmage.org
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
Content-Length: byte-length-of-content
Content-Type: multipart/form-data, Boundary=AAABBB
--AAABBB
content-disposition: form-data; name="campaign_urn"
urn:mobilize:sleep
--AAABBB
content-disposition: form-data; name="campaign_creation_timestamp"
2012-01-01 08:00:00
--AAABBB
content-disposition: form-data; name="client"
android-2.2
--AAABBB
content-disposition: form-data; name="user"
beyonce
--AAABBB
content-disposition: form-data; name="password"
hashedPassword
--AAABBB
content-disposition: form-data; name="surveys"
... JSON data ...
--AAABBB
content-disposition: attachment; name="004cb8dd-27ea-4994-b8b9-f3c83b2cfde2"
content-type: image/jpeg
content-transfer-encoding: binary
... contents of jpeg ...
--AAABBB
Each campaign running in an ohmage application represents a grouping of surveys. Each survey upload is represented by a JSON object that must adhere to the following specification. TODO: link to campaign docs
All fields are required.
| JSON Key | Usage/Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| survey_key | A UUID unique to this survey response. | ||||||||||||||||
| time | An int specifying the survey completion time by the number of milliseconds since the UNIX epoch. | ||||||||||||||||
| timezone | The timezone ID for the timezone of the device when this survey was taken. | ||||||||||||||||
| location_status | A string describing location status. Must be one of: unavailable, valid, inaccurate, gps_off, stale. If the status is unavailable, it is an error to send a location object. | ||||||||||||||||
| location | A JSON object for housing location data.
|
||||||||||||||||
| survey_id | A string defining a survey in the campaign's associated configuration file at the XPath /surveys/survey/id | ||||||||||||||||
| survey_launch_context | A JSON object with variable properties that describes the survey's launch context.
|
||||||||||||||||
| privacy_state | The privacy state of this survey response. If omitted, this defaults to 'private'. | ||||||||||||||||
| responses | A JSON array composed of JSON object prompt responses and/or JSON object repeatable set responses.
|
||||||||||||||||
| Prompt Type | Constraints | Example |
|---|---|---|
| number or hours_before_now | An integer within a range. | `"value":1 |
| text | Free-form text. | `"value":"I just tweeted that I updated my Facebook status." |
| multi_choice | A JSON array of items where each item is an integer key from a table of key-value pairs representing the choices. | `"value":[0,1,2] |
| multi_choice_custom | A JSON array of label values chosen by the user. | `"value":["apple","banana"] |
| single_choice | An item that is an integer key from a table of key-value pairs representing the choices | `"value":1 |
| single_choice_custom | The label value of the item the user chose. | `"value":"spork" |
| photo | A UUID for uniquely labeling the upload of the binary data. | `"value":"fb788b16-34f4-4bdb-886a-e76926399adc" |
| video | A UUID for uniquely labeling the upload of the binary data. | `"value":"fb788b16-34f4-4bdb-886a-e76926399adc" |
| audio | A UUID for uniquely labeling the upload of the binary data. | `"value":"fb788b16-34f4-4bdb-886a-e76926399adc" |
[
{
"survey_key":"6bf5c551-f901-4be7-826a-35c7c78b9265"
"time":1257272467077,
"timezone":"PT",
"location_status":"valid"
"location": {
"latitude":38.8977,
"longitude":-77.0366,
"accuracy":30,
"time":1257272467077,
"timezone":"PT"
},
"survey_launch_context": {
"launch_time":1257272467077,
"launch_timezone":"PT",
"active_triggers":[]
}
"survey_id":"specificStressfulEvent",
"responses": [
{
"prompt_id":"specificStressfulEventHoursAgo",
"value":1
},
{
"prompt_id":"specificStressfulEventWhatHappened",
"value":"I sat on the 405 for an hour in practically stopped traffic."
},
{
"prompt_id":"specificStressfulEventPhoto",
"value":"e5bc0c9a-5773-4088-80ad-af7d0e3c14fb"
}
]
}
]
When the user intentionally skips a question (i.e., by pressing "Skip"), the response must be set to the special string SKIPPED. Whether a prompt is skippable or not depends on its configuration.
"responses":[
{
"prompt_id":"advertisingType",
"value":"SKIPPED"
},...
]
When a prompt is not displayed because of a condition evaluating to false, the string NOT_DISPLAYED must be sent as the response.
"responses":[
{
"prompt_id":"snackChoice",
"value":"NOT_DISPLAYED"
},...
]
{
"result" : "success"
}
See the error page for a description of error codes and their associated descriptions.
Allows reading of survey responses with a variety of output formats and many different ways of controlling the items present in the response.
survey_response/read
| Operation | Participant | Author | Analyst | Supervisor | Admin |
|---|---|---|---|---|---|
| Read Their Own Private or Shared Survey Responses | anytime | N/A | N/A | N/A | anytime |
| Read Someone Else's Shared Survey Responses | never | anytime | if the campaign is shared | anytime | anytime |
| Read Someone Else's Private Survey Responses | never | never | never | anytime | anytime |
- (r) auth_token = A valid authentication token from user/auth_token. May also be set using the Set-Cookie header.
- (r) user = A username of the user attempting to login
- (r) password = The hashed password of the participant taking the survey (see: user/auth).
- (r) campaign_urn = A valid campaign URN for the currently logged in user.
- (r) client = The name of the software client accessing the API.
- (r) column_list = One or more of the URNs in the table below in a comma-separated list or urn:ohmage:special:all.
- (o) end_date = Must be present if start_date is present; allows querying against a date range as a timestamp (eg.
2015-01-01 23:59:59). - (r) output_format = One of json-rows, json-columns, or csv.
- (o) pretty_print = A boolean that if true will indent JSON output.
- (o) prompt_id_list = Optional, but must be present if survey_id_list is not present. A comma separated list of prompt ids which must exist in the campaign being queried. urn:ohmage:special:all is also allowed.
- (o) privacy_state = If present, must be one of "private" or "shared". The output is dependent on the access-control rules governing the role of the logged-in user.
- (o) sort_order = Controls the SQL ORDER BY clause: a comma separated list containing user, timestamp, survey in any order.
- (o) start_date = Optional, but must be present if end_date is present: allows querying against a date range as a timestamp (eg.
2015-01-01 00:00:00). - (o) suppress_metadata = A boolean [true|false] to control whether the metadata section of the output will be returned.
- (o) survey_id_list = Optional, but must be present if prompt_id_list is not present. A comma separated list of survey ids which must exist in the campaign being queried. urn:ohmage:special:all is also allowed.
- (r) user_list = A comma separated list of usernames that must be valid for the campaign being queried. urn:ohmage:special:all is also allowed.
- (o) return_id = A boolean indicating whether to return the primary key of the survey for client update/delete purposes. This parameter is only available for json-rows output.
- (o) collapse = A boolean indicating whether to collapse duplicate results: this is most useful when asking the API to provide specific columns e.g., when you only want the a list of unique users to be returned. This will result in a new key in each "row" for json-rows and a new "column" in json-columns and csv output. The new "key" will be "count" and the new "column" will be "urn:ohmage:context:count".
- (o) num_to_skip = The number of survey responses to skip in reverse chronological order in which they were taken.
- (o) num_to_process = The number of survey responses to process after the skipping those to be skipped via 'num_survey_responses_to_skip'.
- (o) survey_response_id_list = A comma-separated list of survey response IDs. The results will only be of survey responses whose ID is in this list.
- csv output is returned as an attached file
- column_list must a comma-separated list with a maximum length of 10 column URNs or urn:ohmage:special:all may be used to retrieve all columns. For row-based output, this parameter contains the attributes that appear with each "record" in the output.
- both start_date and end_date must be ISO 8601 formatted date values. Both start_date and end_date are optional, but if one is present, the other must also be present. The server will return data for all dates if neither is present.
- For output_format=csv, pretty_print is ignored.
- Both prompt_id_list and survey_id_list are optional, but at least one of them must be present. The maximum number of prompts or surveys is ten. If you want all of the prompts or surveys in a particular campaign, use urn:ohmage:special:all.
- suppress_metadata will cause the metadata section of the output not to be returned. This parameter is ignored for JSON output.
| URN | Description/Notes |
|---|---|
| urn:ohmage:user:id | The user's username in the system. |
| urn:ohmage:context:client | The "client" parameter set on the request for a survey upload. Client here refers to software client as opposed to user. |
| urn:ohmage:context:location:timezone | The timezone of the device when the location object was generated. |
| urn:ohmage:context:timezone | The timezone sent with a survey upload. |
| urn:ohmage:context:utc_timestamp | The epoch millis sent with the survey uploaded converted to a human-readable datetime |
| urn:ohmage:context:launch_context_short | The survey_launch_context sent with a survey upload. The short version contains the launch time and launch timezone. |
| urn:ohmage:context:launch_context_long | The survey_launch_context sent with a survey upload. The long version contains all reminder information that was uploaded with the survey is returned. |
| urn:ohmage:context:location:status | One of unavailable, valid, stale, inaccurate. |
| urn:ohmage:context:location:latitude | If the location_status, is unavailable, this value will be null or the empty string for csv output, otherwise it will be a double representing the latitude. |
| urn:ohmage:context:location:longitude | If the location_status, is unavailable, this value will be null or the empty string for csv output, otherwise it will be a double representing the longitude. |
| urn:ohmage:context:location:timestamp | The epoch milliseconds representing when the location was generated. If the location_status, is unavailable, this value will be null or the empty string for csv output. |
| urn:ohmage:context:location:accuracy | The location accuracy in meters. If the location_status is unavailable, this value will be null or the empty string for csv output. |
| urn:ohmage:context:location:provider | The location provider (e.g., GPS or network). If the location_status is unavailable, this value will be null or the empty string for csv output. |
| urn:ohmage:repeatable_set:id | The repeatable set id, if one exists. |
| urn:ohmage:repeatable_set:iteration | The repeatable set iteration, if one exists. |
| urn:ohmage:survey:id | The survey id of the uploaded survey. Also the same value as the survey id from the associated campaign configuration. |
| urn:ohmage:survey:title | The survey title retrieved from the associated campaign configuration. |
| urn:ohmage:survey:description | The survey description retrieved from the associated campaign configuration. |
| urn:ohmage:survey:privacy_state | The survey's privacy state: private or shared. |
| urn:ohmage:prompt:response | The user's prompt response. This value may be a number, a string, a JSON Array, or a JSON Object, depending on its prompt type When this URN is present in the column list passed to the API, the server will generate a unique column for each prompt in the query output. The label on the prompt column will be urn:ohmage:prompt:promptId where promptId is the actual id of the prompt in its associated configuration file. |
| urn:ohmage:context:epoch_millis | The milliseconds since the UNIX epoch at which time this survey was completed. |
| urn:ohmage:special:all | A special value that tells this API to return all items for a specific parameter e.g., all users would be user_list=urn:special:ohmage:all. This value is supported for user_list, prompt_id_list, survey_id_list, and column_list. |
To do paging, you will need to use the num_survey_responses_to_skip, which will skip responses immediately after aggregating the data beginning with the first record, and num_survey_responses_to_process parameters, which will process this number of records starting after the records to be skipped have been. The responses are aggregated in descending chronological order, so the first survey response to be skipped will be the most recently generated survey response.
For example, if there are 100 records that would be returned, the number of records per page are 10, and the user wants to view the third page, you should pass 20 for num_survey_responses_to_skip and 10 for num_survey_responses_to_process. This will return survey responses 21 through 30.
The numbers do not need to coincide in any way. You may skip 13 and process 43. Also, you may skip and/or process more records than would be returned. If there are only 50 records, you may skip and/or process 100. If you skip more records than would be returned, you will be returned no survey responses. If you attempt to process more than would be returned, it will begin after the number skipped, if any remain, and process until the end of the list and stop.
POST /app/survey_response/read HTTP/1.1
Host: www.andwellness.org
User-Agent: Mozilla/5.0 (Linux; U; Android 1.0; en-us; ...) ...
Content-Length: byte-length of content
Content-Type: application/x-www-form-urlencoded
campaign_urn=urn:campaign:mobilize:sleep
&client=r_web
&user_list=user1,user2
&start_date=2010-09-13
&end_date=2010-09-14
&auth_token=auth_token
&prompt_id_list=urn:ohmage:special:all
&output_format=json-columns
curl -v -d "auth_token=token&campaign_urn=urn:campaign:ca:ucla:Snack&client=r_web&user_list=urn:ohmage:special:all&prompt_id_list=urn:ohmage:special:all&output_format=json-columns&column_list=urn:ohmage:prompt:response" https://dev.mobilizingcs.org/app/survey_response/read
The column output is defined by two sections.
- campaign_name = An echo of the campaign provided to the API
- campaign_version = An echo of the campaign version provided to the API (to be discontinued)
- number_of_prompts = The number of prompt responses in the output
- number_of_surveys = The number of survey responses in the output
- items = An array of the included column names
- total_num_results = The total number of results that match the given criteria outside of paging. While the page may only contain X results, this value will indicate the total number of results, which must be greater than or equal to X.
- An array of objects where each object is labelled by column name (from the items array in the metadata section) and contains an array of values specific to that column. For prompt responses, the values array is accompanied by a context object with the relevant prompt metadata.
{
"result": "success",
"metadata": {
"campaign_urn":"urn:campaign:nih",
"number_of_prompts":3,
"number_of_surveys":1,
"items:[
"urn:ohmage:prompt:id:whatDidYouEat",
"urn:ohmage:prompt:id:foodGroup",
"urn:ohmage:prompt:id:howDoesItMakeYouFeel",
"urn:ohmage:context:user",
"urn:ohmage:context:timestamp",
"urn:ohmage:context:timezone",
"urn:ohmage:context:location:longitude",
"urn:ohmage:context:location:latitude"
],
"total_num_results":87
},
"data": {
"urn:ohmage:context:user":{
"values":["user1","user1","user1"]
}
"urn:ohmage:prompt:id:whatDidYouEat":{
"context": {
"unit":"food unit",
"prompt_type":"single_choice",
"display_type:"category",
"choice_glossary":{
"0":"broccoli",
"1":"salad",
"2":"cookies"
}
}
"values":[0,1,2]
},
"urn:ohmage:prompt:id:foodGroup":{
"context": {
"unit":"food unit",
"prompt_type":"single_choice",
"display_type:"category"
"choice_glossary":{
"0":"vegetable",
"1":"fruit",
"2":"snack"
}
},
values:[0,0,2]
},
"urn:ohmage:prompt:id:howDoesItMakeYouFeel":{
"context": {
"prompt_type":"single_choice",
"display_type:"category"
"choice_glossary":{
"0":"full",
"1":"empty",
"2":"fun"
}
},
values:[0,1,2],
},
"urn:ohmage:context:epoch_millis":{
"values": [
7238973829,2783972895,23894023834
]
},
"urn:ohmage:context:timezone":{
"values": [ "MST", "CST", "EST" ]
},
"urn:ohmage:context:location:longitude":{
"values":[ 43.106, 5.674, -9.7096 ]
},
"urn:ohmage:context:location:latitude":{
"values": [ -84.603, -84.765, 51.579 ]
}
}
}
{
"data": [
{
"client": "android",
"latitude": null,
"launch_context_long": {
"active_triggers": [],
"launch_time": 2390983229,
"launch_timezone":"America/LosAngeles"
},
"launch_context_short": {"launch_time":2390983229, "launch_timezone":"America/LosAngeles"},
"location_accuracy": null,
"location_provider": null,
"location_status": "unavailable",
"location_timestamp": null,
"longitude": null,
"privacy_state": "private",
"repeatable_set_id": null,
"repeatable_set_iteration": null,
"responses": {
"ActivityBeforeSleep": {
"prompt_choice_glossary": {
"0": {"label": "Homework"},
"1": {"label": "Internet"},
"2": {"label": "Games"},
"3": {"label": "TV"},
"4": {"label": "Socializing"},
"5": {"label": "Social-networking"},
"6": {"label": "Chores"},
"7": {"label": "Reading"},
"8": {"label": "Other"}
},
"prompt_display_type": "category",
"prompt_response": 3,
"prompt_text": "What were you doing during the hour before going to bed?",
"prompt_type": "single_choice",
"prompt_unit": "Activity",
"prompt_index":0
},
"HoursOfSleep": {
"prompt_display_type": "measurement",
"prompt_response": 8,
"prompt_text": "How many hours of sleep did you get?",
"prompt_type": "number",
"prompt_unit": "Hours",
"prompt_index":1
},
"PhoneInterruption": {
"prompt_choice_glossary": {
"0": {
"label": "No",
"value": "0"
},
"1": {
"label": "Yes",
"value": "1"
}
},
"prompt_display_type": "category",
"prompt_response": 0,
"prompt_text": "If you woke up during the night, was it because of phone calls/text messages?",
"prompt_type": "single_choice",
"prompt_unit": "Unit",
"prompt_index":2
},
"SleepQuality": {
"prompt_choice_glossary": {
"0": {
"label": "Very bad",
"value": "-2"
},
"1": {
"label": "Bad",
"value": "-1"
},
"2": {
"label": "Ok",
"value": "0"
},
"3": {
"label": "Good",
"value": "1"
},
"4": {
"label": "Very good",
"value": "2"
}
},
"prompt_display_type": "category",
"prompt_response": 3,
"prompt_text": "How would you rate your sleep quality?",
"prompt_type": "single_choice",
"prompt_unit": "Level",
"prompt_index":3
},
"SleepTime": {
"prompt_choice_glossary": {
"0": {"label": "Before 9 pm"},
"1": {"label": "9:00-9:30 pm"},
"10": {"label": "1:30-2:00 am"},
"11": {"label": "After 2:00 am"},
"2": {"label": "9:30-10:00 pm"},
"3": {"label": "10:00-10:30 pm"},
"4": {"label": "10:30-11:00 pm"},
"5": {"label": "11:00-11:30 pm"},
"6": {"label": "11:30 pm-12:00 am"},
"7": {"label": "12:00-12:30 am"},
"8": {"label": "12:30-1:00 am"},
"9": {"label": "1:00-1:30 am"}
},
"prompt_display_type": "event",
"prompt_response": 3,
"prompt_text": "What time did you go to bed last night?",
"prompt_type": "single_choice",
"prompt_unit": "Time",
"prompt_index":4
},
"TimesWakeup": {
"prompt_choice_glossary": {
"0": {
"label": "0",
"value": "0"
},
"1": {
"label": "1",
"value": "1"
},
"2": {
"label": "2",
"value": "2"
},
"3": {
"label": "3 or more",
"value": "3"
}
},
"prompt_display_type": "category",
"prompt_response": 1,
"prompt_text": "How many times did you wake up during the night?",
"prompt_type": "single_choice",
"prompt_unit": "Times",
"prompt_index":5
},
"WakeupTime": {
"prompt_choice_glossary": {
"0": {"label": "Before 5:00 am"},
"1": {"label": "5:00-5:30 am"},
"10": {"label": "9:30-10:00 am"},
"11": {"label": "10:00-10:30 am"},
"12": {"label": "10:30-11:00 am"},
"13": {"label": "11:00-11:30 am"},
"14": {"label": "11:30 am-12:00 pm"},
"15": {"label": "After 12:00 pm"},
"2": {"label": "5:30-6:00 am"},
"3": {"label": "6:00-6:30 am"},
"4": {"label": "6:30-7:00 am"},
"5": {"label": "7:00-7:30 am"},
"6": {"label": "7:30-8:00 am"},
"7": {"label": "8:00-8:30 am"},
"8": {"label": "8:00-9:00 am"},
"9": {"label": "9:00-9:30 am"}
},
"prompt_display_type": "event",
"prompt_response": 2,
"prompt_text": "What time did you wake up this morning?",
"prompt_type": "single_choice",
"prompt_unit": "Time",
"prompt_index":6
},
"timeToFallAsleep": {
"prompt_choice_glossary": {
"0": {"label": "Shorter"},
"1": {"label": "Normal"},
"2": {"label": "Longer"}
},
"prompt_display_type": "category",
"prompt_response": 0,
"prompt_text": "Compared to normal, how long did it take you to fall asleep?",
"prompt_type": "single_choice",
"prompt_unit": "Time",
"prompt_index":7
}
},
"survey_description": "Observe and collect sleep pattern",
"survey_id": "SleepPattern",
"survey_title": "Sleep Pattern",
"time": 239892893289
"timezone": "America/Los_Angeles",
"user": "hollywood.bbf",
"utc_timestamp": "2011-06-01 15:57:32"
},
"metadata":{
"campaign_urn":"urn:campaign:nih",
"number_of_prompts":3,
"number_of_surveys":1,
"items:[
"urn:ohmage:prompt:id:whatDidYouEat",
"urn:ohmage:prompt:id:foodGroup",
"urn:ohmage:prompt:id:howDoesItMakeYouFeel",
"urn:ohmage:context:user",
"urn:ohmage:context:timestamp",
"urn:ohmage:context:timezone",
"urn:ohmage:context:location:longitude",
"urn:ohmage:context:location:latitude"
],
"total_num_results":87
},
"result": "success"
}
This example query
curl -v -d "auth_token=928368c8-b78f-49eb-a214-d98165df01a1
&campaign_urn=urn:campaign:ca:lausd:Addams_HS:CS101:Fall:2011:Sleep
&client=curl
&user_list=josh.test
&start_date=2011-04-16
&end_date=2011-04-26
&prompt_id_list=urn:ohmage:special:all
&output_format=csv
&column_list=urn:ohmage:survey:id,urn:ohmage:survey:title,urn:ohmage:prompt:response"
http://localhost:8080/app/survey_response/read
leads to the following output.
##begin metadata
# {"result":"success";"total_num_results":87;"campaign_urn":"urn:campaign:ca:lausd:Addams_HS:CS101:Fall:2011:Sleep";"number_of_prompts":80;"number_of_surveys":16}
## end metadata
## begin prompt contexts
#{"HowTired":{"unit":null;"display_label":"Tiredness Level";"prompt_type":"single_choice";"choice_glossary":[{"2":{"value":"1";"label":"Less tired"}};{"1":{"value":"0";"label":"Normal"}};{"0":{"value":"-1";"label":"More tired"}}]}}
#{"PhoneInterruption":{"unit":null;"display_label":"Phone/SMS Sleep Interruption";"prompt_type":"single_choice";"choice_glossary":[{"1":{"value":"1";"label":"Yes"}};{"0":{"value":"0";"label":"No"}}]}}
#{"timeToFallAsleep":{"unit":null;"display_label":"Time to Sleep";"prompt_type":"single_choice";"choice_glossary":[{"2":{"label":"Longer"}};{"1":{"label":"Normal"}};{"0":{"label":"Shorter"}}]}}
#{"WakeupTime":{"unit":null;"display_label":"Wakeup time";"prompt_type":"single_choice";"choice_glossary":[{"15":{"label":"After 12:00 pm"}};{"13":{"label":"11:00-11:30 am"}};{"14":{"label":"11:30 am-12:00 pm"}};{"11":{"label":"10:00-10:30 am"}};{"12":{"label":"10:30-11:00 am"}};{"3":{"label":"6:00-6:30 am"}};{"2":{"label":"5:30-6:00 am"}};{"1":{"label":"5:00-5:30 am"}};{"10":{"label":"9:30-10:00 am"}};{"0":{"label":"Before 5:00 am"}};{"7":{"label":"8:00-8:30 am"}};{"6":{"label":"7:30-8:00 am"}};{"5":{"label":"7:00-7:30 am"}};{"4":{"label":"6:30-7:00 am"}};{"9":{"label":"9:00-9:30 am"}};{"8":{"label":"8:00-9:00 am"}}]}}
#{"SleepTime":{"unit":null;"display_label":"Sleep time";"prompt_type":"single_choice";"choice_glossary":[{"3":{"label":"10:00-10:30 pm"}};{"2":{"label":"9:30-10:00 pm"}};{"10":{"label":"1:30-2:00 am"}};{"1":{"label":"9:00-9:30 pm"}};{"0":{"label":"Before 9 pm"}};{"7":{"label":"12:00-12:30 am"}};{"6":{"label":"11:30 pm-12:00 am"}};{"5":{"label":"11:00-11:30 pm"}};{"4":{"label":"10:30-11:00 pm"}};{"9":{"label":"1:00-1:30 am"}};{"8":{"label":"12:30-1:00 am"}};{"11":{"label":"After 2:00 am"}}]}}
#{"SleepQuality":{"unit":null;"display_label":"Sleep quality";"prompt_type":"single_choice";"choice_glossary":[{"3":{"value":"1";"label":"Good"}};{"2":{"value":"0";"label":"Ok"}};{"1":{"value":"-1";"label":"Bad"}};{"0":{"value":"-2";"label":"Very bad"}};{"4":{"value":"2";"label":"Very good"}}]}}
#{"TimesWakeup":{"unit":null;"display_label":"Times wakeup";"prompt_type":"single_choice";"choice_glossary":[{"3":{"value":"3";"label":"3 or more"}};{"2":{"value":"2";"label":"2"}};{"1":{"value":"1";"label":"1"}};{"0":{"value":"0";"label":"0"}}]}}
#{"Concentration":{"unit":null;"display_label":"Concentration Level";"prompt_type":"single_choice";"choice_glossary":[{"2":{"value":"1";"label":"More clear"}};{"1":{"value":"0";"label":"Normal"}};{"0":{"value":"-1";"label":"Less clear"}}]}}
#{"HoursOfSleep":{"unit":null;"display_label":"Number hours of sleep";"prompt_type":"number";"choice_glossary":null}}
#{"ActivityBeforeSleep":{"unit":null;"display_label":"Activity before Sleep";"prompt_type":"single_choice";"choice_glossary":[{"3":{"label":"TV"}};{"2":{"label":"Games"}};{"1":{"label":"Internet"}};{"0":{"label":"Homework"}};{"7":{"label":"Reading"}};{"6":{"label":"Chores"}};{"5":{"label":"Social-networking"}};{"4":{"label":"Socializing"}};{"8":{"label":"Other"}}]}}
## end prompt contexts
## begin data
#HowTired,PhoneInterruption,WakeupTime,TimesWakeup,Concentration,timeToFallAsleep,survey:id,HoursOfSleep,SleepTime,SleepQuality,survey:title,ActivityBeforeSleep
1,null,null,null,-1,null,SleepImpact,null,null,null,Sleep Impact,null
null,1,8,2,null,0,SleepPattern,19,7,-2,Sleep Pattern,1
-1,null,null,null,0,null,SleepImpact,null,null,null,Sleep Impact,null
null,1,3,0,null,2,SleepPattern,12,6,0,Sleep Pattern,8
-1,null,null,null,-1,null,SleepImpact,null,null,null,Sleep Impact,null
null,1,1,3,null,1,SleepPattern,3,5,1,Sleep Pattern,0
1,null,null,null,1,null,SleepImpact,null,null,null,Sleep Impact,null
null,1,15,1,null,0,SleepPattern,12,0,2,Sleep Pattern,5
-1,null,null,null,-1,null,SleepImpact,null,null,null,Sleep Impact,null
null,1,15,1,null,0,SleepPattern,1,7,-2,Sleep Pattern,7
1,null,null,null,1,null,SleepImpact,null,null,null,Sleep Impact,null
null,0,1,3,null,1,SleepPattern,10,7,1,Sleep Pattern,1
-1,null,null,null,0,null,SleepImpact,null,null,null,Sleep Impact,null
null,0,3,3,null,0,SleepPattern,24,6,2,Sleep Pattern,4
1,null,null,null,1,null,SleepImpact,null,null,null,Sleep Impact,null
null,1,5,2,null,2,SleepPattern,3,11,-2,Sleep Pattern,8
## end data
See the error page for a description of error codes and their associated descriptions.
Allows users with the appropriate permissions to change the privacy state of survey responses.
survey_response/update
Campaign participants may update the privacy state of their own survey responses. Campaign supervisors may update the privacy state on someone else's survey responses.
- (r) auth_token = A valid authentication token from user/auth_token.
- (r) client = A string representing the client.
- (r) campaign_urn = The campaign URN to which the survey response belongs.
- (r) survey_key = An id returned from survey_response/read when the return id parameter is set to true.
- (r) privacy_state = Must be one of shared or private.
POST /app/survey_response/update HTTP/1.1
Host: dev.ohmage.org
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
Content-Length: byte-length-of-content
Content-Type: application/x-www-form-urlencoded
auth_token=3dd982c4-5118-11e1-9e19-e4ce8f075a7e
&campaign_urn=urn:campaign:ca:lausd:Addams_HS:CS101:Fall:2011:Advertisement
&survey_key=b62f9808-5118-11e1-81c3-e4ce8f075a7e
&privacy_state=private
&client=curl
curl -v -d "auth_token=5bc26d43-ccad-430a-8d3b-db303f1e56dc&campaign_urn=urn:campaign:ca:lausd:Sleep &survey_key=999999999&privacy_state=shared&client=curl" http://localhost:8080/app/survey_response/update
{
"result" : "success"
}
See the error page for a description of error codes and their associated descriptions.
Allows users with the appropriate permissions to delete survey responses.
survey_response/delete
Campaign participants may delete their own survey responses. Campaign supervisors may delete someone else's survey responses.
- (r) auth_token = A valid authentication token from user/auth_token.
- (r) client = A string representing the client.
- (r) campaign_urn = The campaign URN to which the survey response belongs.
- (r) survey_key = An id returned from survey_response/read when the return id parameter is set to true.
POST /app/survey_response/delete HTTP/1.1
Host: dev.ohmage.org
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
Content-Length: byte-length-of-content
Content-Type: application/x-www-form-urlencoded
auth_token=3dd982c4-5118-11e1-9e19-e4ce8f075a7e
&campaign_urn=urn:campaign:ca:lausd:Advertisement
&survey_key=b62f9808-5118-11e1-81c3-e4ce8f075a7e
&client=curl
curl -v -d "auth_token=3dd982c4-5118-11e1-9e19-e4ce8f075a7e&campaign_urn=urn:campaign:ca:lausd:Advertisement&survey_key=b62f9808-5118-11e1-81c3-e4ce8f075a7e&client=curl" https://dev.mobilizingcs.org/app/survey_response/delete
{
"result" : "success"
}
See the error page for a description of error codes and their associated descriptions.
Allows users with the appropriate permissions to read aggregate data about survey responses. The API takes an id parameter that tells the system which function to perform on the data.
survey_response/function/read
See the access rules for survey_response/read above.
- (r) auth_token = A valid authentication token from user/auth_token. May also be set using the Set-Cookie header.
- (r) user = A username of the user attempting to login
- (r) password = The hashed password of the participant taking the survey (see: user/auth).
- (r) client = A string representing the client.
- (r) campaign_urn = The campaign URN against which the survey response aggregation should be performed.
- (r) id = Function id. The currently supported id is privacy_state.
- (o) privacy_state_item_list = A comma-separated list containing date or survey in any order.
POST /app/survey_response/function/read HTTP/1.1
Host: dev.ohmage.org
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
Content-Length: byte-length-of-content
Content-Type: application/x-www-form-urlencoded
auth_token=3dd982c4-5118-11e1-9e19-e4ce8f075a7e
&campaign_urn=urn:campaign:ca:ucla:cens:josh_prompt_types_test
&client=curl
&id=privacy_state
curl -v -d "auth_token=3dd982c4-5118-11e1-9e19-e4ce8f075a7e&campaign_urn=urn:campaign:ca:ucla:cens:josh_prompt_types_test&client=curl&id=privacy_state" https://dev.mobilizingcs.org/app/survey_response/function/read
{
"result" : "success"
"data" : <The data based on the function id.>
}
See the error page for a description of error codes and their associated descriptions.
Returns the count of the privacy states of every survey response in a campaign.
When this function is called, a second parameter is allowed, privacy_state_item_list.
- This will subdivide the results based on each item in the list.
- It is optional and, if omitted or empty, will return only the counts for each privacy state.
- The value should be a comma-separated string whose values may be any combination of the following:
date
| ||
survey
|
The result is a JSONObject.
- The keys are the privacy states.
- The value for each key is a JSON Array of JSON Objects, where each JSON Object describes the aggregation for this privacy state. The JSON Object's keys may be:
(r) count
|
|
(o) date
|
|
(o) survey_id
|
For example, if no privacy_state_item_list was given or was empty, an example result would be:
{
"private":[
{
"count":3
}
],
"shared":[
{
"count":4
}
]
}
This means that there were a total of 7 survey responses for the given campaign and that 3 of them are private and 4 of them are shared.
As another example, if "survey_id" was given for the privacy_state_item_list, an example result would be:
{
"private":[
{
"count":2
"survey_id":"survey1"
},
{
"count":1
"survey_id":"survey2"
},
],
"shared":[
{
"count":4
"survey_id":"survey2"
}
]
}
This means that there were, again, a total of 7 survey responses for the given campaign and that 3 of them are private and 4 of them are shared. Also, 2 of them are from survey "survey1" and 5 of them are from survey "survey2".
As a final example, if both "survey_id" and "date" were given for the privacy_state_item_list, an example result would be:
{
"private":[
{
"count":1
"survey_id":"survey1"
"date":12345600000
},
{
"count":1
"survey_id":"survey1"
"date":65432100000
},
{
"count":1
"survey_id":"survey2"
"date":65432100000
},
],
"shared":[
{
"count":1
"survey_id":"survey2"
"date":65432100000
},
{
"count":3
"survey_id":"survey2"
"date":33333300000
}
]
}
This means that there were, again, a total of 7 survey responses for the given campaign and that 3 of them are private and 4 of them are shared. Also, again, 2 of them are from survey "survey1" and 5 of them are from survey "survey2". We can also see that several of them were taken on the same day, but because their privacy state and/or survey ID are different they aren't put in the same bucket.