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 CodeDescription
200Successful Operation
400Required parameter 'start_date' is missing
Required parameter 'end_date' is missing
401Access token is missing or invalid
403Not a valid key value pair in Authorization header
404The requested API could not be found. Please review your URL
429Too many requests hit the API too quickly

Output Data

Field NameTypeDescription
user_idIntegerUnique ID to identify a user
app_versionStringVersion of the mobile app user has installed
time_zoneStringTimezone 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_dateStringDate for which compliance is being calculated
worn_hoursFloatNumber of hours for which user was wearing device that day
raw_data_hoursFloatNote 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)
Query Params
date
required

The date in the format yyyy-MM-dd. For start day, all data gets picked up starting 00:00:00.

date
required

The date in the format yyyy-MM-dd. For stop date, all data is picked up until 23:59:59.

Responses
200

successful operation

400

The request was invalid or cannot be otherwise served. An accompanying error message will explain further. There can be following errors-
- No start date or stop date
- Duration between start and stop time is more than 30 days

401

Access token is missing or invalid

404

The requested API could not be found. Please review your URL.

429

Too many requests hit the API too quickly.

Language
Credentials
URL