From 7cc5f274404ba828363a765838dd445247c98dc9 Mon Sep 17 00:00:00 2001 From: Nosh Petigara Date: Mon, 2 Nov 2015 13:36:48 -0500 Subject: [PATCH 1/4] Added documentation for downloading health data This documentation includes all parameters from this pull request: https://github.com/tidepool-org/tide-whisperer/pull/16 --- _docs/tidepool-api/downloading.md | 41 ++++++++++++++++++++++++++++--- 1 file changed, 38 insertions(+), 3 deletions(-) diff --git a/_docs/tidepool-api/downloading.md b/_docs/tidepool-api/downloading.md index e6c3da3..c24d81e 100644 --- a/_docs/tidepool-api/downloading.md +++ b/_docs/tidepool-api/downloading.md @@ -11,11 +11,46 @@ For other parts of the API, including logging in and uploading data, navigate ba ## Health data -[Link to format documentation] - ### Get data -[For Care Team, for date range] +Health data can be downloaded through Tidepool's /data/ API. This API takes a user ID, and optionally start and end timestamps, data type, and data subtype. The userId indicates the user for which data is to be downloaded. If no optional parameters are included, all data is returned. If startdate and/or enddate are included, then only objects within the date range are returned. If type or subtype are included, then only objects matching those types or subtypes are returned. Matching data is returned as an array of Tidepool objects. The format for the requests is: + +``` +GET /data/:userId?startdate=&enddate=&type=&subtype= +x-tidepool-session-token: + +``` +Parameter details: +* userId: the ID of the user you want to retrieve data for +* type (optional) : The Tidepool data type to search for. Only objects with a type field matching the specified type param will be returned. Can be /userid?type=smbg or a comma seperated list e.g /userid?type=smgb,cbg . If is a comma seperated +list, then objects matching any of the types will be returned +* subtype (optional) : The Tidepool data subtype to search for. Only objects with a subtype field matching the specified subtype param will be returned. Can be /userid?subtype=physicalactivity or a comma seperated list e.g /userid?subtypetype=physicalactivity,steps . If it is a comma seperated list, then objects matching any of the subtypes will be returned +* startdate (optional) : Only objects with 'time' field equal to or greater than start date will be returned. Must be in ISO date/time format e.g. 2015-10-10T15:00:00.000Z +* enddate (optional) : Only objects with 'time' field less than to or equal to start date will be returned. Must be in ISO date/time format e.g. 2015-10-10T15:00:00.000Z + +Example: +``` +GET /data/450f582c78?startdate=2015-10-08T15:00:00.000Z&enddate=2015-10-11T15:00:00.000Z&type=smbg +``` +Response: +``` +[ +{ + "conversionOffset": 0, + "deviceId": "postman1", + "deviceTime": "2015-10-10T11:00:00", + "id": "p3uac1etornvvsgitlvddaaks6t18k1a", + "time": "2015-10-10T15:00:00.000Z", + "timezoneOffset": -240, + "type": "smbg", + "units": "mmol/L", + "uploadId": "0001", + "value": 6.66089758925464 + }, + {...}, + {...} +] +``` ## Notes From fc38079696fbe04915a286b6c483f6eeaf4a02f7 Mon Sep 17 00:00:00 2001 From: Nosh Petigara Date: Wed, 4 Nov 2015 16:56:48 -0500 Subject: [PATCH 2/4] Added links for Physical Activity and Step Count --- _docs/data-model-v1/v1.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_docs/data-model-v1/v1.md b/_docs/data-model-v1/v1.md index 1e0b1b5..3d2e5d0 100644 --- a/_docs/data-model-v1/v1.md +++ b/_docs/data-model-v1/v1.md @@ -28,6 +28,8 @@ For notes on migrations required for different versions of the data model [pleas * [Settings](settings) * [Upload](upload) * [Wizard](wizard) +* [Physical Activity](physicalactivity) +* [Step Count](stepcount) ## Common Fields From c707917c4afaf1d3054b5c27b6464b15be2f2da4 Mon Sep 17 00:00:00 2001 From: Nosh Petigara Date: Wed, 4 Nov 2015 23:27:24 -0500 Subject: [PATCH 3/4] First docs for Physical activity object --- _docs/data-model-v1/v1/physicalactivity.md | 89 ++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 _docs/data-model-v1/v1/physicalactivity.md diff --git a/_docs/data-model-v1/v1/physicalactivity.md b/_docs/data-model-v1/v1/physicalactivity.md new file mode 100644 index 0000000..1b79cd6 --- /dev/null +++ b/_docs/data-model-v1/v1/physicalactivity.md @@ -0,0 +1,89 @@ +--- +layout: defaults +title: Physical Activity V1 +published: true +--- + +# Physical Activity + +A physical activity object represents the an activity such as a running, cycling, etc that a user performs. These are typically recorded by wearable activity trackers (such as Jawbone or Fitbit) or standalone fitness apps (such as Strava or Runkeeper) and imported into Tidepool + +An Physical Activity record includes information on the time and provenance of the activity as well as information about the activity such as the type of activity, the distance covered, calories burned, etc + +## Object +A typical physical activity object is as follows: + +~~~json + { + "type": "physicalActivity", + + "time": "2015-10-24T16:17:50.000Z", + "timezoneOffset":-240, + "conversionOffset":0, + "deviceId": "runkeeper-A1234", + "uploadId": "0001", + + "datapoint": { + "header":{ + "acquisition_provenance": { + "source_name": "Runkeeper HealthGraph API", + "modality": "sensed", + "external_id": "/fitnessActivities/679963655" + } + + }, + "body": { + "effective_time_frame": { + "time_interval": { + "start_date_time": "2015-10-24T12:17:50-04:00", + "duration": { + "unit": "sec", + "value": 148.311 + } + } + }, + "activity_name": "Running", + "distance": { + "unit": "m", + "value": 10.3929068646607 + } + }, + "kcal_burned": { + "unit": "kcal", + "value": 7 + }, + "reported_activity_intensity": "moderate" + + } + } +~~~ + +### Common Fields +For the definitions of `type`, `time`, `timezoneOffset`, `conversionOffset`, `deviceId`, `uploadId` see common fields in the data model documentation + +### Datapoint +The `datapoint` field contains the information about the physical activity including its provenance and details of the physical activity. The format of data point objects are based on Open mHealth Schemas. For further reference :http://www.openmhealth.org/documentation/#/schema-docs/overview and http://www.openmhealth.org/documentation/#/schema-docs/schema-library/schemas/omh_physical-activity + +#### Header +The `header` field contains the details on how the event was captured: + +`source_name`: (required) describes the device or app that this data was reteived from + +`modality`: (optional) Can be either 'sensed' or 'self-reported' depending on whether the activity was recorded by the device/app or manually entered by the user + +`external_id`: (optional) An ID that identify the activity reading in the source system. + +#### Body +The `body` field adds details about the physical activity the user performed: + +`start_date_time`: Timestamp of when the activity started. Includes a time zone + +`duration`: The length of time the activity was performed for + +`activity_name`: The name of the activity e.g. 'running' + +`distance`: (optional) distance covered during an activity + +`kcal_burned`: (optional) kCal burned during the activity + +`reported_activity_intensity`: (optional) Intensity level reported by the user - one of "light", "moderate" or "vigorous" From d665b9d1fa7cc6b236d24ca659464b625e0ee25f Mon Sep 17 00:00:00 2001 From: Nosh Petigara Date: Thu, 5 Nov 2015 13:30:09 -0500 Subject: [PATCH 4/4] First docs for Step Count object --- _docs/data-model-v1/v1/stepcount.md | 73 +++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 _docs/data-model-v1/v1/stepcount.md diff --git a/_docs/data-model-v1/v1/stepcount.md b/_docs/data-model-v1/v1/stepcount.md new file mode 100644 index 0000000..3a2debd --- /dev/null +++ b/_docs/data-model-v1/v1/stepcount.md @@ -0,0 +1,73 @@ +--- +layout: defaults +title: Step Count V1 +published: true +--- + +# Step Count + +A step object represents the number of steps a user has taken in a period of time. These are typically recorded by wearable activity trackers (such as Jawbone or Fitbit) or standalone fitness apps and imported into Tidepool + +An step count record includes information on the time and provenance of when the step count was recorded, as well as the number of steps the user has taken during the recording period + +## Object +A typical step count object is as follows: + +~~~json + { + "type": "stepCount", + + "time": "2015-10-14T04:00:50.000Z", + "timezoneOffset":-240, + "conversionOffset":0, + "deviceId": "jawbone-A1234", + "uploadId": "0001", + + "datapoint": { + "header":{ + "acquisition_provenance": { + "source_name": "Jawbone UP API", + "modality": "sensed", + "external_id": "43t7Tx40joGTZSuJe1H4I8KzpgjxT7a7" + } + + }, + "body": { + "effective_time_frame": { + "time_interval": { + "start_date_time": "2015-10-14T00:00:50-04:00", + "end_date_time": "2015-10-14T23:14:51-04:00" + } + }, + + "step_count": 7851 + + } + } + } +~~~ + +### Common Fields +For the definitions of `type`, `time`, `timezoneOffset`, `conversionOffset`, `deviceId`, `uploadId` see common fields in the data model documentation + +### Datapoint +The `datapoint` field contains the information about the step count recording including its provenance and number of steps taken by the user. The format of data point objects are based on Open mHealth Schemas. For further reference :http://www.openmhealth.org/documentation/#/schema-docs/overview and http://www.openmhealth.org/documentation/#/schema-docs/schema-library/schemas/omh_step-count + +#### Header +The `header` field contains the details on how the event was captured: + +`source_name`: (required) describes the device or app that this data was reteived from + +`modality`: (optional) Can be either 'sensed' or 'self-reported' depending on whether the step count was recorded by the device/app or manually entered by the user + +`external_id`: (optional) An ID that identify the step count recording in the source system. + +#### Body +The `body` field adds details about the steps recorded for the the user: + +`start_date_time`: Timestamp for the start of the recording period. Includes a time zone + +`end_date_time`: Timestamp of the end of the recording period. Includes a time zone + +`step_count`: The number of steps taken by the user during the recording period +