Unprocessed raw sensor data API

Headers

This API requires API Access Token available at the Research portal. Set this up as HTTP header before calling the API.

Response format

Unprocessed raw sensor data is sampled 25 Hz (i.e. 25 rows every second). Since this API may result in a very large amount of data, this API works in following steps -

Once API is called, unprocessed sensor time series data is generated and stored as a gzip file (gzip of a CSV file) inside secured Spire Health cloud.
API returns URL of the gzip file in JSON format.
Since raw unprocessed data file can be large, it may take some time to prepare the raw data file. Once you receive the URL, it's recommended that you wait for 60 seconds before sending the request to download the file (note that the delay is built into the code sample below).
Use the URL to download the data on your computer or to a storage system.
In order to use the data in your program, unzip the file into a CSV format and use it inside your program (see the code sample below for details)
Here is how CSV file for unprocessed sensor data will look like -

Response Code	Description
200	Successful Operation
400	Error messages for invalid input parameters. For example - Only upto 24 hours of data is allowed in a single call. Please adjust start and stop time accordingly User with email doesn't exist or not authorized!
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

Output data is a time series with 25 data samples returned every second. Here is the format of data -

Field Name	Type	Description
user_id	Integer	Unique ID to identify a user
device_id	String	Spire Health wearable device that captured the data
time	date-time	Local date & time where data was captured
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
force	Integer	Data from Force Sensor
x_accel	Integer	Accelerometer X-axis value
y_accel	Integer	Accelerometer Y-axis value
z_accel	Integer	Accelerometer Z-axis value
ppg	Integer	Data from PPG sensor
proximity	Integer	Data from Touch sensor

Program samples to test out API

Use the program samples below to test out APIs with your own research data -

cURL

Program below will return a URL for gzip file. Use that URL to download gzip file. Then, unzip to get CSV file with phsyiological timeseries data.

curl -X GET \
  'https://research-api.spire.io/v1/unprocessed_sensor_timeseries?start_time=2019-02-01%2000:00:00&stop_time=2019-02-01%2023:59:59&[email protected]' \
  -H 'Authorization: Bearer 284e8f3320a8500c58ea5b8e7829bdd676ea941bb573bb250d51c0b82f68e19d'

Python

Python program sample below has steps to download unprocessed raw sensor data in CSV format.

import requests
import pandas as pd
from http import HTTPStatus
import time
import os

### File name to download gzip file
output_file_name = "unprocessed_sensor_data.gz"

### Get the URL for phsyiological timeseries data gzip file 
headers = {'Authorization': str('284e8f3320a8500c58ea5b8e7829bdd676ea941bb573bb250d51c0b82f68e19d'), 'Content-type': 'application/json'}
params = {'start_time': '2019-02-27 00:00:00', 'stop_time': '2019-02-27 23:59:59', 'email': '[email protected]'}
response_with_url = requests.get(f'https://research-api.spire.io/v1/unprocessed_sensor_timeseries', params=params, headers=headers)

if response_with_url.status_code == HTTPStatus.OK:
    unprocessed_sensor_data_url = response_with_url.json()['url']
    try:
        ### Download the gzip file 
        time.sleep(60) 
        gzip_file = requests.get(url=unprocessed_sensor_data_url, stream=True)
        if gzip_file.status_code == 404:
            print ("Delaying by 60 seconds more to download " + output_file_name)
            time.sleep(60) 
            gzip_file = requests.get(url=unprocessed_sensor_data_url, stream=True)
    except:
        print ("Exception got triggered for " + output_file_name)
        time.sleep(60) 
        gzip_file = requests.get(url=unprocessed_sensor_data_url, stream=True)
    if gzip_file.status_code == HTTPStatus.OK:
        ### Store the file on the local file system
        with open(output_file_name, 'wb') as gf:
            for chunk in gzip_file.iter_content(chunk_size=65536):
                gf.write(chunk)
    else:
        print ("Returned status code is: " + str(gzip_file.status_code))
        print (gzip_file.text)
    
else:
    print ("Returned status code is: " + str(response_with_url.status_code))
    print (response_with_url.text)

### Read the file into Pandas Dataframe
if os.path.isfile(output_file_name):
    raw_data = pd.read_csv(output_file_name,compression='gzip')
    print (raw_data.shape)