Annotations

An annotation represents an activity or survey completed by a subject, or a label associated to a point in a recording.

Refer to What types of survey questions are available? for a list of question types and formats.

Get Annotations

Get a list of annotations for a subject.

URL

GET https://mc10cloud.com/api/v1/studies/{studyId}/subjects/{subjectId}/annotations?from={from}&to={to}&type={type}

Parameters

  • studyId: Study UUID

  • subjectId: Subject UUID

  • from: (Optional) Beginning timestamp (UTC), inclusive

  • to: (Optional) Ending timestamp (UTC), inclusive

  • type: (Optional) One or more annotation types as discrete parameters (type=a&type=b). Acceptable types are "activity", "diary" (survey), "question", "recording" (a label entered by a study administrator) and "subject" (a label entered by the system, e.g. "SYSTEM:POSTURE_CALIBRATION")

Sample Response

The following example shows two "activity" annotations and one "diary" (survey) annotation. The "event" object is a reference to the activity or diary definition on the study. The property authorId is a reference to the logged-in user; in this case, the user is an administrator using the BioStamp® nPoint™ Investigator app.

{
"items": [
{
"authorId": "814eca80-505b-11e7-85fd-0a87d285401b",
"createdTs": 1525707658866,
"displayName": "Annotation",
"event": {
"displayName": "Timed Up and Go Test",
"id": "7f958711-4f1a-11e8-a47c-028eb5a65596",
"type": "activity"
},
"id": "09e20520-520d-11e8-a47c-028eb5a65596",
"startTs": 1525707625119,
"stopTs": 1525707651963,
"studyId": "f7888660-4f14-11e8-a47c-028eb5a65596",
"subjectId": "22785730-520b-11e8-a47c-028eb5a65596"
},
{
"authorId": "814eca80-505b-11e7-85fd-0a87d285401b",
"createdTs": 1525708363916,
"displayName": "Annotation",
"event": {
"displayName": "6-Minute Walk Test",
"id": "39d538f2-4f16-11e8-bd02-0a84ea04a300",
"type": "activity"
},
"id": "ae201cc0-520e-11e8-a47c-028eb5a65596",
"startTs": 1525707765318,
"stopTs": 1525708125321,
"studyId": "f7888660-4f14-11e8-a47c-028eb5a65596",
"subjectId": "22785730-520b-11e8-a47c-028eb5a65596"
},
{
"authorId": "814eca80-505b-11e7-85fd-0a87d285401b",
"createdTs": 1525708390187,
"displayName": "Annotation",
"event": {
"displayName": "Food Survey",
"id": "f1ab4b92-4f16-11e8-bd02-0a84ea04a300",
"type": "diary"
},
"id": "bdc8bfb0-520e-11e8-bd02-0a84ea04a300",
"startTs": 1525708389982,
"stopTs": 1525708389982,
"studyId": "f7888660-4f14-11e8-a47c-028eb5a65596",
"subjectId": "22785730-520b-11e8-a47c-028eb5a65596"
},
...
],
"size": 39
}

Get Annotation

Get a specific annotation by its ID.

URL

GET https://mc10cloud.com/api/v1/studies/{studyId}/subjects/{subjectId}/annotations/{annotationId}

Parameters

  • studyId: Study UUID

  • subjectId: Subject UUID

  • annotationId: Annotation UUID

Sample Response

The following example shows that the activity "Stressball Squeezes" began at 5/7/2018, 11:40:25 AM EDT and ended at 5/7/2018, 11:40:51 AM EDT.

{
"authorId": "22785730-520b-11e8-a47c-028eb5a65596",
"createdTs": 1525707658866,
"displayName": "Annotation",
"event": {
"displayName": "Stressball Squeezes",
"id": "d820b5d2-4f15-11e8-a47c-028eb5a65596",
"type": "activity"
},
"id": "09e20520-520d-11e8-a47c-028eb5a65596",
"startTs": 1525707625119,
"stopTs": 1525707651963,
"studyId": "f7888660-4f14-11e8-a47c-028eb5a65596",
"subjectId": "22785730-520b-11e8-a47c-028eb5a65596"
}

Get Annotation Q/A

Get question/answer pairs corresponding to a completed activity or survey. This is a convenience method that joins the question metadata to the actual answer submitted by a subject.

URL

GET https://mc10cloud.com/api/v1/studies/{studyId}/annotations/{annotationId}/questions

Parameters

  • studyId: Study UUID

  • annotationId: Annotation UUID

Sample Response

The following example shows questions presented (and answers received) as part of an activity.

{
"items": [
{
"answer": "YES",
"createdTs": 1525708364087,
"id": "ae3a3470-520e-11e8-bd02-0a84ea04a300",
"question": "Was the subject able to complete this activity?",
"type": "BOOLEAN"
},
{
"answer": "Moderately fast",
"createdTs": 1525708363950,
"id": "ae254ce0-520e-11e8-bd02-0a84ea04a300",
"question": "How fast did the subject walk?",
"type": "MULTIPLECHOICE"
}
],
"size": 2
}

Download Annotations CSV

Download annotations for a subject in CSV format.

This method returns content as text/csv.

URL

GET https://mc10cloud.com/api/v1/archives/{studyId}/subjects/{subjectId}/annotations

Parameters

  • studyId: Study UUID

  • subjectId: Subject UUID

Sample Response

"Timestamp (ms)","AnnotationId","EventType","AuthorId","Start Timestamp (ms)","Stop Timestamp (ms)","Value"
"1525726695652","Activity:Walking","Walking","subj09","1525726546783","1525726695223",""
"1525726786002","ActivityQuestion:How fast did you walk?","How fast did you walk?","subj09","1525726695223","1525726695223","Slow"
"1525726876115","Diary:Mood Survey","Mood Survey","subj09","1525726876024","1525726876024",""
"1525726876319","DiaryQuestion:How are you feeling right now?","How are you feeling right now?","subj09","1525726876024","1525726876024","Content"
"1525726876472","DiaryQuestion:How hungry are you, on a scale of 0 to 10?","How hungry are you, on a scale of 0 to 10?","subj09","1525726876024","1525726876024","3"