In order for studies or research projects to succeed, it's important that users are wearing devices for certain hours all the time. This API is used to fetch data on user's worn compliance. API returns worn hours broken by days between start and end date.
Headers
This API just requires API Access Token available at the Research portal. Set this up as HTTP header before calling the API.
Response format
This API returns User data in a JSON format -
[
{
"user_id": 0,
"app_version": "string",
"time_zone": "string",
"compliance_date": "2019-02-21",
"worn_hours": 0,
"raw_data_hours": 0
}
]
| Response Code | Description |
|---|---|
| 200 | Successful Operation |
| 400 | Required parameter 'start_date' is missing Required parameter 'end_date' is missing |
| 401 | Access token is missing or invalid |
| 403 | Not a valid key value pair in Authorization header |
| 404 | The requested API could not be found. Please review your URL |
| 429 | Too many requests hit the API too quickly |
Output Data
| Field Name | Type | Description |
|---|---|---|
| user_id | Integer | Unique ID to identify a user |
| app_version | String | Version of the mobile app user has installed |
| time_zone | String | Timezone in which data was captured. For example - 'America/Chicago','Australia/Brisbane','Europe/Stockholm'. More detailed list available at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones |
| compliance_date | String | Date for which compliance is being calculated |
| worn_hours | Float | Number of hours for which user was wearing device that day |
| raw_data_hours | Float | Note that Spire Health Tag device is capable of keeping raw unprocessed data for 45 minutes. So in order for us to get the raw unprocessed data, phone needs to be with the user all the time. This field indicates the number of hours for which raw unprocessed data came through that day. |
Program samples to test out API
Use the program samples below to test out APIs with your own research data -
cURL
'https://research-api.spire.io/v1/user_compliance?start_date=2019-02-20&stop_date=2019-02-20' \
-H 'Authorization: Bearer 9f33707110d21885da378b7482e530492de0a1b2b0d279172112357b975f4fc1'
Python
Python program sample below calls User compliance API to get user compliance data for a date range and saves the data into a Pandas data frame.
import requests
from http import HTTPStatus
import pandas as pd
headers = {'Authorization': str('Bearer 9f33707110d21885da378b7482e530492de0a1b2b0d279172112357b975f4fc1'), 'Content-type': 'application/json'}
params = {'start_date': '2019-02-20', 'stop_date': '2019-02-20'}
user_compliance = requests.get(f'https://research-api.spire.io/v1/user_compliance', params=params, headers=headers)
if user_compliance.status_code == HTTPStatus.OK:
user_compliance_pandas = pd.DataFrame(user_compliance.json(),columns=user_compliance.json()[0].keys())
print (user_compliance_pandas.head())
else:
print ("Returned status code is: " + str(user_compliance.status_code))
print (user_compliance.text)