API Doc v0.1

The Zeo API is a set of web services that allow third parties to develop applications that allow users full
access to their individual sleep records. A set of operations is provided using HTTP and can return data in
either JSON or XML formats. All API operations must be authenticated using either Basic Auth or OAuth.
Sample code is be provided to illustrate best practices for using the API and to provide a starting point for
new Zeo-aware applications.

Using the Zeo API, developers will have the ability to access nightly sleep data including ZQ scores,
total sleep time, the number of times woken, and the amount of REM, light, and deep sleep. Additionally,
developers will be able to display a sleep graph, showing how the user slept in 5-minute increments
throughout the night.

Introduction
API Basics
Identification and Authentication
Notification Service
Code Samples
Service Catalog

Introduction

To use the API, you will need a Zeo issued key which must be included with all requests. It is freely available for non-commercial use by any developer and may be licensed (or freely licensed in some cases) for commercial use by prior arrangement.

You can apply for a key here

API Basics

Request format

The Zeo Web API is REST-based. All communication is over SSL. Requests are sent as HTTPS GET requests.

A typical Zeo Web API service request follows this template :

https://api.myzeo.com:8443/zeows/api/[version]/[response_type]/[service_name]/[action_name]?key=[key]&[parameters]

Where :
[version] is the requested service version (i.e. v1),
[response_type] is the requested response output type (i.e. json). This is an optional argument (default returns XML)
[service_name] is the requested service (i.e. sleeperService),
[action_name] is the action you want to perform on the requested service (i.e. getSleepStatsByDateRange),
[key] is the Zeo-issued API key you received when you signed up (i.e. B0372F610DBA1D7C19F987835F05F4CA1),
[parameters] are parameters, mandatory or optional, passed to the requested service.

For every call, the version, service_name, action_name, key parameters are all required.

Response format

Responses to such requests can be either XML or JSON documents. By default, XML format is returned. To specify either return format, the request "Accept" header can be modified to include "application/xml" for XML or "application/json" for json. In the case that you cannot modify the request "Accept" header, and need JSON output, you can force the api to return JSON by changing the URL as discussed above with 'json' in the response_type section.

XML responses look like the following:

JSON responses look like the following:

In this example, the sleepRecords is empty, indicating no data.
Any single response will provide a mandatory status field. A response with a status of 0 is OK. A response with a non-zero status will also include an <errMsg> tag describing the error. Please refer to the Error code sections to get a hint as to what went wrong, and why.

A XML library is available for most programming languages at http://www.xml.com.

A JSON library is available for most programming languages at http://www.json.org.

Identification and Authentication

You typically use the Zeo Web API to retrieve data related to a given user, for example, sleep ZQ scores and nightly sleep data. A user is part of an account.

An account is what Zeo users use to log into their dashboard. An account is uniquely defined by an email address. For access to be granted to a given account, its password (chosen by the user at registration time) is needed.

There are two types of authentication, HTTP Basic and OAUTH. If you wish to access the API via OAUTH, your app must be hosted on an external server. If you are not accessing the API programatically, and doing it through a web browser, you will be brought to a login screen if you have not already authenticated.

When accessing the API directly or via a 3rd party (i.e. using OAUTH), the user account credentials must be entered (email address and password). Once authenticated, the user will not be asked to log in again until the session expires.

To learn more about HTTP Basic Authentication, Please see http://en.wikipedia.org/wiki/Basic_access_authentication.
To learn more about OAUTH, please see http://oauth.net/

Notification Service for Third Parties

The most effective way for third parties to retrieve measurement updates is to setup notifications (some might call it "Push") for the users they are interested in. Each time the subscribed users upload their sleep data, the Zeo Web API will send notifications to all their monitoring third parties.

Subscriptions will not be performed if the user has not allowed its profile to be public. A given user can not be subscribed by more than 10 third parties. The user must subscribe to the notification service directly from the third party website, and must login with their own credentials.

When the Zeo Web API sees that subscriber data has been modified, it sends a notification to the subscribing third party application. The notification contains information that helps to determine what should be downloaded to remain in sync.

Notifications subscriptions last until the user or the third party application unsubscribes from the notification service.

The subscription can be revoked at any time. To find out more, download our Notification Feature PDF, or contact us at DeveloperRelations@myZeo.com. Also, please see our terms of service here

Code Samples

We've put together some samples in different languages to help illustrate the documentation.
We've included samples and libraries in the following languages:

Google Gadget (includes OAUTH sample)
Java (uses basic Auth)
Perl (uses basic Auth)
Perl Library for Zeo API (this library kindly developed by Eric Blue)
PHP (uses basic Auth)
Python (uses basic Auth)
Ruby Gem for Zeo API (this gem kindly developed by DailyBurn)

You can download samples from here

Service Catalog

Overall Average Functions:

getOverallAverageZQScore - Returns the average ZQ score for the user.
getOverallAverageDayFeelScore - Returns the average score for how the user felt during the day.
getOverallAverageMorningFeelScore - Returns the average score for how the user felt in the morning.
getOverallAverageSleepStealerScore - Returns the average sleep stealer score for the user.

Date Functions:

getAllDatesWithSleepData - Returns an array of ZeoDate objects representing dates for which sleep data is available.
getDatesWithSleepDataInRange - Returns an array of ZeoDate objects for which sleep data is available inclusive in dates.
getSleepStatsForDate - Returns the SleepStats for the specified date.
getSleepRecordForDate - Returns the SleepRecord for the specified date.

Paging Functions:

getPreviousSleepStats - Returns the SleepStats (grouped by day) for the latest date prior to the specified date.
getPreviousSleepRecord - Returns the SleepRecord for the latest date prior to the specified date.
getNextSleepStats - Returns the SleepStats (grouped by day) for the earliest date after the specified date.
getNextSleepRecord - Returns the SleepStats for the earliest date after the specified date.
getEarliestSleepStats - Returns the SleepStats (grouped by day) with the earliest date on record for the current user.
getEarliestSleepRecord - Returns the SleepRecord with the earliest date on record for the current user.
getLatestSleepStats - Returns the SleepStats (grouped by day) with the latest date on record for the current user.
getLatestSleepRecord - Returns the SleepRecord with the latest date on record for the current user.

Miscellaneous Functions:

logout - Logs the user out of the API and closes the session.

getOverallAverageZQScore

This returns the average ZQ score for the user.

Parameters

Response

Example

Parameters

Required	Name	Type	Description
required	key	string	The API key of the API consumer.

Each response contains the following attributes:

Response Attributes
Name	Description
status	A status code, useful for determining success of the call. See status codes table.
versionApi	An versionApi (Attribute), informing the caller which version of the API is being used
versionBuild	An versionBuild (Attribute), informing the caller which build of the API is being used
reqId	The reqId identifies the request (reserved for later use)
rspId	The rspId identifies the response (reserved for later use)

Each response contains the following fields:

Response fields
Name	Description
name	The name tells the caller which function was called.
value	The value includes the ZQ value as an integer. If there is no data, -1 will be returned.

Status codes

Code	Description
0	Operation was successfull
1	General Error (Unknown)
2	Parameter not provided or in incorrect format
3	No account exists
4	No account exists for session
5	An API Key is required
6	API Key does not match caller domain.
7	API Key does not exist.
8	API called too many times.

getOverallAverageDayFeelScore

This returns an average score of how the user feels during the day.

Parameters

Response

Example

Parameters

Required	Name	Type	Description
required	key	string	The API key of the API consumer.

Each response contains the following attributes:

Response Attributes
Name	Description
status	A status code, useful for determining success of the call. See status codes table.
versionApi	An versionApi (Attribute), informing the caller which version of the API is being used
versionBuild	An versionBuild (Attribute), informing the caller which build of the API is being used
reqId	The reqId identifies the request (reserved for later use)
rspId	The rspId identifies the response (reserved for later use)

Each response contains the following fields:

Response fields
Name	Description
name	The name tells the caller which function was called.
value	The value includes the day feel score value as an integer. If there is no data, -1 will be returned.

Status codes

Code	Description
0	Operation was successfull
1	General Error (Unknown)
2	Parameter not provided or in incorrect format
3	No account exists
4	No account exists for session
5	An API Key is required
6	API Key does not match caller domain.
7	API Key does not exist.
8	API called too many times.

getOverallAverageMorningFeelScore

This returns an average score of how the user feels in the morning.

Parameters

Response

Example

Parameters

Required	Name	Type	Description
required	key	string	The API key of the API consumer.

Each response contains the following attributes:

Response Attributes
Name	Description
status	A status code, useful for determining success of the call. See status codes table.
versionApi	An versionApi (Attribute), informing the caller which version of the API is being used
versionBuild	An versionBuild (Attribute), informing the caller which build of the API is being used
reqId	The reqId identifies the request (reserved for later use)
rspId	The rspId identifies the response (reserved for later use)

Each response contains the following fields:

Response fields
Name	Description
name	The name tells the caller which function was called.
value	The value includes the feel score value as an integer. If there is no data, -1 will be returned.

Status codes

Code	Description
0	Operation was successfull
1	General Error (Unknown)
2	Parameter not provided or in incorrect format
3	No account exists
4	No account exists for session
5	An API Key is required
6	API Key does not match caller domain.
7	API Key does not exist.
8	API called too many times.

getOverallAverageSleepStealerScore

This returns an average score of the number of sleep stealers.

Parameters

Response

Example

Parameters

Required	Name	Type	Description
required	key	string	The API key of the API consumer.

Each response contains the following attributes:

Response Attributes
Name	Description
status	A status code, useful for determining success of the call. See status codes table.
versionApi	An versionApi (Attribute), informing the caller which version of the API is being used
versionBuild	An versionBuild (Attribute), informing the caller which build of the API is being used
reqId	The reqId identifies the request (reserved for later use)
rspId	The rspId identifies the response (reserved for later use)

Each response contains the following fields:

Response fields
Name	Description
name	The name tells the caller which function was called.
value	The value includes the score value as an integer. If there is no data, -1 will be returned.

Status codes

Code	Description
0	Operation was successfull
1	General Error (Unknown)
2	Parameter not provided or in incorrect format
3	No account exists
4	No account exists for session
5	An API Key is required
6	API Key does not match caller domain.
7	API Key does not exist.
8	API called too many times.

getAllDatesWithSleepData

Returns an array of ZeoDate objects representing dates for which sleep data is available.

Parameters

Response

Example

Parameters

Required	Name	Type	Description
required	key	string	The API key of the API consumer.

Each response contains the following attributes:

Response Attributes
Name	Description
status	A status code, useful for determining success of the call. See status codes table.
versionApi	An versionApi (Attribute), informing the caller which version of the API is being used
versionBuild	An versionBuild (Attribute), informing the caller which build of the API is being used
reqId	The reqId identifies the request (reserved for later use)
rspId	The rspId identifies the response (reserved for later use)

Each response contains the following fields:

Response fields
Name	Description
name	The name tells the caller which function was called.
dateList	A set of ZeoDate objects each of which include the day, month, and year

The ZeoDate object contains the following attributes and fields:

ZeoDate Fields
Name	Description
day	The numeric day of a calendar month
month	The numeric month of a calendar year
year	The 4-digit year.

Status codes

Code	Description
0	Operation was successfull
1	General Error (Unknown)
2	Parameter not provided or in incorrect format
3	No account exists
4	No account exists for session
5	An API Key is required
6	API Key does not match caller domain.
7	API Key does not exist.
8	API called too many times.

getDatesWithSleepDataInRange

Returns an array of ZeoDate objects representing dates for which sleep data is available.

Parameters

Response

Example

Parameters

Required	Name	Type	Description
required	key	string	The API key of the API consumer.
optional	dateFrom	string	The bottom of the date range. If not specified API assumes the first record.
optional	dateTo	string	The top of the date range. If not specified API assumes the last record.

Each response contains the following attributes:

Response Attributes
Name	Description
status	A status code, useful for determining success of the call. See status codes table.
versionApi	An versionApi (Attribute), informing the caller which version of the API is being used
versionBuild	An versionBuild (Attribute), informing the caller which build of the API is being used
reqId	The reqId identifies the request (reserved for later use)
rspId	The rspId identifies the response (reserved for later use)

Each response contains the following fields:

Response fields
Name	Description
name	The name tells the caller which function was called.
dateList	A set of ZeoDate objects each of which include the day, month, and year

The ZeoDate object contains the following attributes and fields:

ZeoDate Fields
Name	Description
day	The numeric day of a calendar month
month	The numeric month of a calendar year
year	The 4-digit year.

Status codes

Code	Description
0	Operation was successfull
1	General Error (Unknown)
2	Parameter not provided or in incorrect format
3	No account exists
4	No account exists for session
5	An API Key is required
6	API Key does not match caller domain.
7	API Key does not exist.
8	API called too many times.

getSleepStatsForDate

Returns a SleepStats object for the date requested. Null will be returned if date specified has no sleep stats.

Parameters

Response

Example

Parameters

Required	Name	Type	Description
required	key	string	The API key of the API consumer.
required	date	string	The requested date. Date must be in YEAR-MONTH-DAY format.

Each response contains the following attributes:

Response Attributes
Name	Description
status	A status code, useful for determining success of the call. See status codes table.
versionApi	An versionApi (Attribute), informing the caller which version of the API is being used
versionBuild	An versionBuild (Attribute), informing the caller which build of the API is being used
reqId	The reqId identifies the request (reserved for later use)
rspId	The rspId identifies the response (reserved for later use)

Each response contains the following fields:

Response fields
Name	Description
name	The name tells the caller which function was called.
sleepStats	A SleepStats object

The SleepStats object contains the following objects, attributes and fields:

SleepStats Fields
Name	Description
awakenings	The number of times the individual woke up during the period
awakeningsZqPoints	The number of ZQ points due to awakenings
bedTime	A ZeoDateTime object describing the bed time
grouping	The SleepStatsGrouping Enum describing the method in which the data was averaged
morningFeel	An integer from 1-5 describing how the user felt that morning (1=bad,5=great!)
riseTime	A ZeoDateTime object describing the rise time
startDate	A ZeoDate object describing the start date for the SleepStats object
timeInDeep	The amount of time spent (in minutes) in deep sleep
timeInDeepPercentage	The amount of time spent (in percentage of total) in deep sleep
timeInDeepZqPoints	The number of ZQ points accounting for deep sleep
timeInLight	The amount of time spent (in minutes) in light sleep
timeInLightPercentage	The amount of time spent (in percentage of total) in light sleep
timeInLightZqPoints	The number of ZQ points accounting for light sleep
timeInRem	The amount of time spent (in minutes) in Rem sleep
timeInRemPercentage	The amount of time spent (in percentage of total) in Rem sleep
timeInRemZqPoints	The number of ZQ points accounting for Rem sleep
timeInWake	The amount of time spent (in minutes) awake
timeInWakePercentage	The amount of time spent (in percentage of total) awake
timeInWakeZqPoints	The number of ZQ points accounting for being awake
timeToZ	The amount of time (in minutes) it took to fall asleep
totalZ	The total time asleep (in minutes)
totalZZqPoints	The number of ZQ points accounting for Total Z
zq	The overall ZQ score for this sleep period

The ZeoDateTime object contains the following attributes and fields:

ZeoDateTime Fields
Name	Description
year	The 4-digit year.
month	The numeric month of a calendar year
day	The numeric day of a calendar month
hour	The numeric hour of a 24-hour day
minute	The minute of the hour
second	The second of the minute

The ZeoDate object contains the following attributes and fields:

ZeoDate Fields
Name	Description
day	The numeric day of a calendar month
month	The numeric month of a calendar year
year	The 4-digit year.

The SleepStatsGrouping ENUM object contains the following values:

SleepStatsGrouping values
Name	Description
COMBINED	If using date range: This takes all records within the specified inclusive date range and average them all together to a single averaged result If using by count: take the number of daily records specified and average them
DAILY	Stats averaged over each day
WEEKLY	Stats averaged over each week
MONTHLY	Stats averaged over each month

Status codes

Code	Description
0	Operation was successfull
1	General Error (Unknown)
2	Parameter not provided or in incorrect format
3	No account exists
4	No account exists for session
5	An API Key is required
6	API Key does not match caller domain.
7	API Key does not exist.
8	API called too many times.

getSleepRecordForDate

Returns a SleepRecord object for the date requested. Null will be returned if date specified has no sleep record.

Parameters

Response

Example

Parameters

Required	Name	Type	Description
required	key	string	The API key of the API consumer.
required	date	string	The requested date. Date must be in YEAR-MONTH-DAY format.

Each response contains the following attributes:

Response Attributes
Name	Description
status	A status code, useful for determining success of the call. See status codes table.
versionApi	An versionApi (Attribute), informing the caller which version of the API is being used
versionBuild	An versionBuild (Attribute), informing the caller which build of the API is being used
reqId	The reqId identifies the request (reserved for later use)
rspId	The rspId identifies the response (reserved for later use)

Each response contains the following fields:

Response fields
Name	Description
name	The name tells the caller which function was called.
sleepRecord	A SleepRecord object

The SleepRecord object contains the following objects, attributes and fields:

SleepRecord Fields
Name	Description
awakenings	The number of times the individual woke up during the period
awakeningsZqPoints	The number of ZQ points due to awakenings
bedTime	A ZeoDateTime object describing the bed time
grouping	The SleepStatsGrouping Enum describing the method in which the data was averaged
morningFeel	An integer from 1-5 describing how the user felt that morning (1=bad,5=great!)
riseTime	A ZeoDateTime object describing the rise time
startDate	A ZeoDate object describing the start date for the SleepStats object
timeInDeep	The amount of time spent (in minutes) in deep sleep
timeInDeepPercentage	The amount of time spent (in percentage of total) in deep sleep
timeInDeepZqPoints	The number of ZQ points accounting for deep sleep
timeInLight	The amount of time spent (in minutes) in light sleep
timeInLightPercentage	The amount of time spent (in percentage of total) in light sleep
timeInLightZqPoints	The number of ZQ points accounting for light sleep
timeInRem	The amount of time spent (in minutes) in Rem sleep
timeInRemPercentage	The amount of time spent (in percentage of total) in Rem sleep
timeInRemZqPoints	The number of ZQ points accounting for Rem sleep
timeInWake	The amount of time spent (in minutes) awake
timeInWakePercentage	The amount of time spent (in percentage of total) awake
timeInWakeZqPoints	The number of ZQ points accounting for being awake
timeToZ	The amount of time (in minutes) it took to fall asleep
totalZ	The total time asleep (in minutes)
totalZZqPoints	The number of ZQ points accounting for Total Z
zq	The overall ZQ score for this sleep period
alarmReason	The AlarmReason value describes why the alarm rang
alarmRingIndex	The index in the sleep graph which the alarm rang
dayFeel	The feel score for the day
sleepGraph	This SleepStage value repeats multiple times to describe a sleep graph.
sleepGraphStartTime	A ZeoDateTime object describing the start time for the graph
sleepStealerScore	The overall score for any sleep stealers. -1 means no data.
wakeWindowEndIndex	If smartwake is being used, indicates the index of the end of the wake window/td>
wakeWindowShow	A boolean field, valid values are true or false
wakeWindowStartIndex	If smartwake is being used, indicates the index of the start of the wake window

The ZeoDateTime object contains the following attributes and fields:

ZeoDateTime Fields
Name	Description
year	The 4-digit year.
month	The numeric month of a calendar year
day	The numeric day of a calendar month
hour	The numeric hour of a 24-hour day
minute	The minute of the hour
second	The second of the minute

The ZeoDate object contains the following attributes and fields:

ZeoDate Fields
Name	Description
day	The numeric day of a calendar month
month	The numeric month of a calendar year
year	The 4-digit year.

The AlarmReason ENUM object contains the following values:

AlarmReason values
Name	Description
REM_TO_NON_REM_TRANSITION	SmartWake detected REM to non-REM transition and rang alarm.
NON_REM_TO_REM_TRANSITION	SmartWake detected non-REM to REM transition and rang alarm.
WAKE	SmartWake detected wake and rang alarm.
DEEP_RISING	SmartWake detected sleep depth rising and rang alarm.
END_OF_WAKE_WINDOW	Set alarm time was reached. SmartWake may or may not be active.
NO_ALARM	Alarm did not ring.

The SleepStatsGrouping ENUM object contains the following values:

SleepStatsGrouping values
Name	Description
COMBINED	If using date range: This takes all records within the specified inclusive date range and average them all together to a single averaged result If using by count: take the number of daily records specified and average them
DAILY	Stats averaged over each day
WEEKLY	Stats averaged over each week
MONTHLY	Stats averaged over each month

The SleepStage ENUM object contains the following values:

SleepStage values
Name	Description
UNDEFINED	Represents a time block where no data is available.
WAKE	Represents a time block where the subject was awake.
REM	Represents a time block where the subject was in REM sleep.
LIGHT	Represents a time block where the subject was in LIGHT sleep.
DEEP	Represents a time block where the subject was in DEEP sleep.

Status codes

Code	Description
0	Operation was successfull
1	General Error (Unknown)
2	Parameter not provided or in incorrect format
3	No account exists
4	No account exists for session
5	An API Key is required
6	API Key does not match caller domain.
7	API Key does not exist.
8	API called too many times.

getPreviousSleepStats

Returns the SleepStats (grouped by day) for the latest date prior to the specified date.

Parameters

Response

Example

Parameters

Required	Name	Type	Description
required	key	string	The API key of the API consumer.
required	date	string	The requested date. Date must be in YEAR-MONTH-DAY format.

Each response contains the following attributes:

Response Attributes
Name	Description
status	A status code, useful for determining success of the call. See status codes table.
versionApi	An versionApi (Attribute), informing the caller which version of the API is being used
versionBuild	An versionBuild (Attribute), informing the caller which build of the API is being used
reqId	The reqId identifies the request (reserved for later use)
rspId	The rspId identifies the response (reserved for later use)

Each response contains the following fields:

Response fields
Name	Description
name	The name tells the caller which function was called.
sleepStats	A SleepStats object

The SleepStats object contains the following objects, attributes and fields:

SleepStats Fields
Name	Description
awakenings	The number of times the individual woke up during the period
awakeningsZqPoints	The number of ZQ points due to awakenings
bedTime	A ZeoDateTime object describing the bed time
grouping	The SleepStatsGrouping Enum describing the method in which the data was averaged
morningFeel	An integer from 1-5 describing how the user felt that morning (1=bad,5=great!)
riseTime	A ZeoDateTime object describing the rise time
startDate	A ZeoDate object describing the start date for the SleepStats object
timeInDeep	The amount of time spent (in minutes) in deep sleep
timeInDeepPercentage	The amount of time spent (in percentage of total) in deep sleep
timeInDeepZqPoints	The number of ZQ points accounting for deep sleep
timeInLight	The amount of time spent (in minutes) in light sleep
timeInLightPercentage	The amount of time spent (in percentage of total) in light sleep
timeInLightZqPoints	The number of ZQ points accounting for light sleep
timeInRem	The amount of time spent (in minutes) in Rem sleep
timeInRemPercentage	The amount of time spent (in percentage of total) in Rem sleep
timeInRemZqPoints	The number of ZQ points accounting for Rem sleep
timeInWake	The amount of time spent (in minutes) awake
timeInWakePercentage	The amount of time spent (in percentage of total) awake
timeInWakeZqPoints	The number of ZQ points accounting for being awake
timeToZ	The amount of time (in minutes) it took to fall asleep
totalZ	The total time asleep (in minutes)
totalZZqPoints	The number of ZQ points accounting for Total Z
zq	The overall ZQ score for this sleep period

The ZeoDateTime object contains the following attributes and fields:

ZeoDateTime Fields
Name	Description
year	The 4-digit year.
month	The numeric month of a calendar year
day	The numeric day of a calendar month
hour	The numeric hour of a 24-hour day
minute	The minute of the hour
second	The second of the minute

The ZeoDate object contains the following attributes and fields:

ZeoDate Fields
Name	Description
day	The numeric day of a calendar month
month	The numeric month of a calendar year
year	The 4-digit year.

The SleepStatsGrouping ENUM object contains the following values:

SleepStatsGrouping values
Name	Description
COMBINED	If using date range: This takes all records within the specified inclusive date range and average them all together to a single averaged result If using by count: take the number of daily records specified and average them
DAILY	Stats averaged over each day
WEEKLY	Stats averaged over each week
MONTHLY	Stats averaged over each month

Status codes

Code	Description
0	Operation was successfull
1	General Error (Unknown)
2	Parameter not provided or in incorrect format
3	No account exists
4	No account exists for session
5	An API Key is required
6	API Key does not match caller domain.
7	API Key does not exist.
8	API called too many times.

getPreviousSleepRecord

Returns the SleepRecord for the latest date prior to the specified date.

Parameters

Response

Example

Parameters

Required	Name	Type	Description
required	key	string	The API key of the API consumer.
required	date	string	The requested date. Date must be in YEAR-MONTH-DAY format.

Each response contains the following attributes:

Response Attributes
Name	Description
status	A status code, useful for determining success of the call. See status codes table.
versionApi	An versionApi (Attribute), informing the caller which version of the API is being used
versionBuild	An versionBuild (Attribute), informing the caller which build of the API is being used
reqId	The reqId identifies the request (reserved for later use)
rspId	The rspId identifies the response (reserved for later use)

Each response contains the following fields:

Response fields
Name	Description
name	The name tells the caller which function was called.
sleepRecord	A SleepRecord object

The SleepRecord object contains the following objects, attributes and fields:

SleepRecord Fields
Name	Description
awakenings	The number of times the individual woke up during the period
awakeningsZqPoints	The number of ZQ points due to awakenings
bedTime	A ZeoDateTime object describing the bed time
grouping	The SleepStatsGrouping Enum describing the method in which the data was averaged
morningFeel	An integer from 1-5 describing how the user felt that morning (1=bad,5=great!)
riseTime	A ZeoDateTime object describing the rise time
startDate	A ZeoDate object describing the start date for the SleepStats object
timeInDeep	The amount of time spent (in minutes) in deep sleep
timeInDeepPercentage	The amount of time spent (in percentage of total) in deep sleep
timeInDeepZqPoints	The number of ZQ points accounting for deep sleep
timeInLight	The amount of time spent (in minutes) in light sleep
timeInLightPercentage	The amount of time spent (in percentage of total) in light sleep
timeInLightZqPoints	The number of ZQ points accounting for light sleep
timeInRem	The amount of time spent (in minutes) in Rem sleep
timeInRemPercentage	The amount of time spent (in percentage of total) in Rem sleep
timeInRemZqPoints	The number of ZQ points accounting for Rem sleep
timeInWake	The amount of time spent (in minutes) awake
timeInWakePercentage	The amount of time spent (in percentage of total) awake
timeInWakeZqPoints	The number of ZQ points accounting for being awake
timeToZ	The amount of time (in minutes) it took to fall asleep
totalZ	The total time asleep (in minutes)
totalZZqPoints	The number of ZQ points accounting for Total Z
zq	The overall ZQ score for this sleep period
alarmReason	The AlarmReason value describes why the alarm rang
alarmRingIndex	The index in the sleep graph which the alarm rang
dayFeel	The feel score for the day
sleepGraph	This SleepStage value repeats multiple times to describe a sleep graph.
sleepGraphStartTime	A ZeoDateTime object describing the start time for the graph
sleepStealerScore	The overall score for any sleep stealers. -1 means no data.
wakeWindowEndIndex	If smartwake is being used, indicates the index of the end of the wake window/td>
wakeWindowShow	A boolean field, valid values are true or false
wakeWindowStartIndex	If smartwake is being used, indicates the index of the start of the wake window

The ZeoDateTime object contains the following attributes and fields:

ZeoDateTime Fields
Name	Description
year	The 4-digit year.
month	The numeric month of a calendar year
day	The numeric day of a calendar month
hour	The numeric hour of a 24-hour day
minute	The minute of the hour
second	The second of the minute

The ZeoDate object contains the following attributes and fields:

ZeoDate Fields
Name	Description
day	The numeric day of a calendar month
month	The numeric month of a calendar year
year	The 4-digit year.

The AlarmReason ENUM object contains the following values:

AlarmReason values
Name	Description
REM_TO_NON_REM_TRANSITION	SmartWake detected REM to non-REM transition and rang alarm.
NON_REM_TO_REM_TRANSITION	SmartWake detected non-REM to REM transition and rang alarm.
WAKE	SmartWake detected wake and rang alarm.
DEEP_RISING	SmartWake detected sleep depth rising and rang alarm.
END_OF_WAKE_WINDOW	Set alarm time was reached. SmartWake may or may not be active.
NO_ALARM	Alarm did not ring.

The SleepStatsGrouping ENUM object contains the following values:

SleepStatsGrouping values
Name	Description
COMBINED	If using date range: This takes all records within the specified inclusive date range and average them all together to a single averaged result If using by count: take the number of daily records specified and average them
DAILY	Stats averaged over each day
WEEKLY	Stats averaged over each week
MONTHLY	Stats averaged over each month

The SleepStage ENUM object contains the following values:

SleepStage values
Name	Description
UNDEFINED	Represents a time block where no data is available.
WAKE	Represents a time block where the subject was awake.
REM	Represents a time block where the subject was in REM sleep.
LIGHT	Represents a time block where the subject was in LIGHT sleep.
DEEP	Represents a time block where the subject was in DEEP sleep.

Status codes

Code	Description
0	Operation was successfull
1	General Error (Unknown)
2	Parameter not provided or in incorrect format
3	No account exists
4	No account exists for session
5	An API Key is required
6	API Key does not match caller domain.
7	API Key does not exist.
8	API called too many times.

getNextSleepStats

Returns the SleepStats (grouped by day) for the earliest date after the specified date.

Parameters

Response

Example

Parameters

Required	Name	Type	Description
required	key	string	The API key of the API consumer.
required	date	string	The requested date. Date must be in YEAR-MONTH-DAY format.

Each response contains the following attributes:

Response Attributes
Name	Description
status	A status code, useful for determining success of the call. See status codes table.
versionApi	An versionApi (Attribute), informing the caller which version of the API is being used
versionBuild	An versionBuild (Attribute), informing the caller which build of the API is being used
reqId	The reqId identifies the request (reserved for later use)
rspId	The rspId identifies the response (reserved for later use)

Each response contains the following fields:

Response fields
Name	Description
name	The name tells the caller which function was called.
sleepStats	A SleepStats object

The SleepStats object contains the following objects, attributes and fields:

SleepStats Fields
Name	Description
awakenings	The number of times the individual woke up during the period
awakeningsZqPoints	The number of ZQ points due to awakenings
bedTime	A ZeoDateTime object describing the bed time
grouping	The SleepStatsGrouping Enum describing the method in which the data was averaged
morningFeel	An integer from 1-5 describing how the user felt that morning (1=bad,5=great!)
riseTime	A ZeoDateTime object describing the rise time
startDate	A ZeoDate object describing the start date for the SleepStats object
timeInDeep	The amount of time spent (in minutes) in deep sleep
timeInDeepPercentage	The amount of time spent (in percentage of total) in deep sleep
timeInDeepZqPoints	The number of ZQ points accounting for deep sleep
timeInLight	The amount of time spent (in minutes) in light sleep
timeInLightPercentage	The amount of time spent (in percentage of total) in light sleep
timeInLightZqPoints	The number of ZQ points accounting for light sleep
timeInRem	The amount of time spent (in minutes) in Rem sleep
timeInRemPercentage	The amount of time spent (in percentage of total) in Rem sleep
timeInRemZqPoints	The number of ZQ points accounting for Rem sleep
timeInWake	The amount of time spent (in minutes) awake
timeInWakePercentage	The amount of time spent (in percentage of total) awake
timeInWakeZqPoints	The number of ZQ points accounting for being awake
timeToZ	The amount of time (in minutes) it took to fall asleep
totalZ	The total time asleep (in minutes)
totalZZqPoints	The number of ZQ points accounting for Total Z
zq	The overall ZQ score for this sleep period

The ZeoDateTime object contains the following attributes and fields:

ZeoDateTime Fields
Name	Description
year	The 4-digit year.
month	The numeric month of a calendar year
day	The numeric day of a calendar month
hour	The numeric hour of a 24-hour day
minute	The minute of the hour
second	The second of the minute

The ZeoDate object contains the following attributes and fields:

ZeoDate Fields
Name	Description
day	The numeric day of a calendar month
month	The numeric month of a calendar year
year	The 4-digit year.

The SleepStatsGrouping ENUM object contains the following values:

SleepStatsGrouping values
Name	Description
COMBINED	If using date range: This takes all records within the specified inclusive date range and average them all together to a single averaged result If using by count: take the number of daily records specified and average them
DAILY	Stats averaged over each day
WEEKLY	Stats averaged over each week
MONTHLY	Stats averaged over each month

Status codes

Code	Description
0	Operation was successfull
1	General Error (Unknown)
2	Parameter not provided or in incorrect format
3	No account exists
4	No account exists for session
5	An API Key is required
6	API Key does not match caller domain.
7	API Key does not exist.
8	API called too many times.

getNextSleepRecord

Returns the SleepStats for the earliest date after the specified date.

Parameters

Response

Example

Parameters

Required	Name	Type	Description
required	key	string	The API key of the API consumer.
required	date	string	The requested date. Date must be in YEAR-MONTH-DAY format.

Each response contains the following attributes:

Response Attributes
Name	Description
status	A status code, useful for determining success of the call. See status codes table.
versionApi	An versionApi (Attribute), informing the caller which version of the API is being used
versionBuild	An versionBuild (Attribute), informing the caller which build of the API is being used
reqId	The reqId identifies the request (reserved for later use)
rspId	The rspId identifies the response (reserved for later use)

Each response contains the following fields:

Response fields
Name	Description
name	The name tells the caller which function was called.
sleepRecord	A SleepRecord object

The SleepRecord object contains the following objects, attributes and fields:

SleepRecord Fields
Name	Description
awakenings	The number of times the individual woke up during the period
awakeningsZqPoints	The number of ZQ points due to awakenings
bedTime	A ZeoDateTime object describing the bed time
grouping	The SleepStatsGrouping Enum describing the method in which the data was averaged
morningFeel	An integer from 1-5 describing how the user felt that morning (1=bad,5=great!)
riseTime	A ZeoDateTime object describing the rise time
startDate	A ZeoDate object describing the start date for the SleepStats object
timeInDeep	The amount of time spent (in minutes) in deep sleep
timeInDeepPercentage	The amount of time spent (in percentage of total) in deep sleep
timeInDeepZqPoints	The number of ZQ points accounting for deep sleep
timeInLight	The amount of time spent (in minutes) in light sleep
timeInLightPercentage	The amount of time spent (in percentage of total) in light sleep
timeInLightZqPoints	The number of ZQ points accounting for light sleep
timeInRem	The amount of time spent (in minutes) in Rem sleep
timeInRemPercentage	The amount of time spent (in percentage of total) in Rem sleep
timeInRemZqPoints	The number of ZQ points accounting for Rem sleep
timeInWake	The amount of time spent (in minutes) awake
timeInWakePercentage	The amount of time spent (in percentage of total) awake
timeInWakeZqPoints	The number of ZQ points accounting for being awake
timeToZ	The amount of time (in minutes) it took to fall asleep
totalZ	The total time asleep (in minutes)
totalZZqPoints	The number of ZQ points accounting for Total Z
zq	The overall ZQ score for this sleep period
alarmReason	The AlarmReason value describes why the alarm rang
alarmRingIndex	The index in the sleep graph which the alarm rang
dayFeel	The feel score for the day
sleepGraph	This SleepStage value repeats multiple times to describe a sleep graph.
sleepGraphStartTime	A ZeoDateTime object describing the start time for the graph
sleepStealerScore	The overall score for any sleep stealers. -1 means no data.
wakeWindowEndIndex	If smartwake is being used, indicates the index of the end of the wake window/td>
wakeWindowShow	A boolean field, valid values are true or false
wakeWindowStartIndex	If smartwake is being used, indicates the index of the start of the wake window

The ZeoDateTime object contains the following attributes and fields:

ZeoDateTime Fields
Name	Description
year	The 4-digit year.
month	The numeric month of a calendar year
day	The numeric day of a calendar month
hour	The numeric hour of a 24-hour day
minute	The minute of the hour
second	The second of the minute

The ZeoDate object contains the following attributes and fields:

ZeoDate Fields
Name	Description
day	The numeric day of a calendar month
month	The numeric month of a calendar year
year	The 4-digit year.

The AlarmReason ENUM object contains the following values:

AlarmReason values
Name	Description
REM_TO_NON_REM_TRANSITION	SmartWake detected REM to non-REM transition and rang alarm.
NON_REM_TO_REM_TRANSITION	SmartWake detected non-REM to REM transition and rang alarm.
WAKE	SmartWake detected wake and rang alarm.
DEEP_RISING	SmartWake detected sleep depth rising and rang alarm.
END_OF_WAKE_WINDOW	Set alarm time was reached. SmartWake may or may not be active.
NO_ALARM	Alarm did not ring.

The SleepStatsGrouping ENUM object contains the following values:

SleepStatsGrouping values
Name	Description
COMBINED	If using date range: This takes all records within the specified inclusive date range and average them all together to a single averaged result If using by count: take the number of daily records specified and average them
DAILY	Stats averaged over each day
WEEKLY	Stats averaged over each week
MONTHLY	Stats averaged over each month

The SleepStage ENUM object contains the following values:

SleepStage values
Name	Description
UNDEFINED	Represents a time block where no data is available.
WAKE	Represents a time block where the subject was awake.
REM	Represents a time block where the subject was in REM sleep.
LIGHT	Represents a time block where the subject was in LIGHT sleep.
DEEP	Represents a time block where the subject was in DEEP sleep.

Status codes

Code	Description
0	Operation was successfull
1	General Error (Unknown)
2	Parameter not provided or in incorrect format
3	No account exists
4	No account exists for session
5	An API Key is required
6	API Key does not match caller domain.
7	API Key does not exist.
8	API called too many times.

getEarliestSleepStats

Returns the SleepStats (grouped by day) with the earliest date on record for the current user.

Parameters

Response

Example

Parameters

Required	Name	Type	Description
required	key	string	The API key of the API consumer.

Each response contains the following attributes:

Response Attributes
Name	Description
status	A status code, useful for determining success of the call. See status codes table.
versionApi	An versionApi (Attribute), informing the caller which version of the API is being used
versionBuild	An versionBuild (Attribute), informing the caller which build of the API is being used
reqId	The reqId identifies the request (reserved for later use)
rspId	The rspId identifies the response (reserved for later use)

Each response contains the following fields:

Response fields
Name	Description
name	The name tells the caller which function was called.
sleepStats	A SleepStats object

The SleepStats object contains the following objects, attributes and fields:

SleepStats Fields
Name	Description
awakenings	The number of times the individual woke up during the period
awakeningsZqPoints	The number of ZQ points due to awakenings
bedTime	A ZeoDateTime object describing the bed time
grouping	The SleepStatsGrouping Enum describing the method in which the data was averaged
morningFeel	An integer from 1-5 describing how the user felt that morning (1=bad,5=great!)
riseTime	A ZeoDateTime object describing the rise time
startDate	A ZeoDate object describing the start date for the SleepStats object
timeInDeep	The amount of time spent (in minutes) in deep sleep
timeInDeepPercentage	The amount of time spent (in percentage of total) in deep sleep
timeInDeepZqPoints	The number of ZQ points accounting for deep sleep
timeInLight	The amount of time spent (in minutes) in light sleep
timeInLightPercentage	The amount of time spent (in percentage of total) in light sleep
timeInLightZqPoints	The number of ZQ points accounting for light sleep
timeInRem	The amount of time spent (in minutes) in Rem sleep
timeInRemPercentage	The amount of time spent (in percentage of total) in Rem sleep
timeInRemZqPoints	The number of ZQ points accounting for Rem sleep
timeInWake	The amount of time spent (in minutes) awake
timeInWakePercentage	The amount of time spent (in percentage of total) awake
timeInWakeZqPoints	The number of ZQ points accounting for being awake
timeToZ	The amount of time (in minutes) it took to fall asleep
totalZ	The total time asleep (in minutes)
totalZZqPoints	The number of ZQ points accounting for Total Z
zq	The overall ZQ score for this sleep period

The ZeoDateTime object contains the following attributes and fields:

ZeoDateTime Fields
Name	Description
year	The 4-digit year.
month	The numeric month of a calendar year
day	The numeric day of a calendar month
hour	The numeric hour of a 24-hour day
minute	The minute of the hour
second	The second of the minute

The ZeoDate object contains the following attributes and fields:

ZeoDate Fields
Name	Description
day	The numeric day of a calendar month
month	The numeric month of a calendar year
year	The 4-digit year.

The SleepStatsGrouping ENUM object contains the following values:

SleepStatsGrouping values
Name	Description
COMBINED	If using date range: This takes all records within the specified inclusive date range and average them all together to a single averaged result If using by count: take the number of daily records specified and average them
DAILY	Stats averaged over each day
WEEKLY	Stats averaged over each week
MONTHLY	Stats averaged over each month

Status codes

Code	Description
0	Operation was successfull
1	General Error (Unknown)
2	Parameter not provided or in incorrect format
3	No account exists
4	No account exists for session
5	An API Key is required
6	API Key does not match caller domain.
7	API Key does not exist.
8	API called too many times.

getEarliestSleepRecord

Returns the SleepRecord with the earliest date on record for the current user.

Parameters

Response

Example

Parameters

Required	Name	Type	Description
required	key	string	The API key of the API consumer.

Each response contains the following attributes:

Response Attributes
Name	Description
status	A status code, useful for determining success of the call. See status codes table.
versionApi	An versionApi (Attribute), informing the caller which version of the API is being used
versionBuild	An versionBuild (Attribute), informing the caller which build of the API is being used
reqId	The reqId identifies the request (reserved for later use)
rspId	The rspId identifies the response (reserved for later use)

Each response contains the following fields:

Response fields
Name	Description
name	The name tells the caller which function was called.
sleepRecord	A SleepRecord object

The SleepRecord object contains the following objects, attributes and fields:

SleepRecord Fields
Name	Description
awakenings	The number of times the individual woke up during the period
awakeningsZqPoints	The number of ZQ points due to awakenings
bedTime	A ZeoDateTime object describing the bed time
grouping	The SleepStatsGrouping Enum describing the method in which the data was averaged
morningFeel	An integer from 1-5 describing how the user felt that morning (1=bad,5=great!)
riseTime	A ZeoDateTime object describing the rise time
startDate	A ZeoDate object describing the start date for the SleepStats object
timeInDeep	The amount of time spent (in minutes) in deep sleep
timeInDeepPercentage	The amount of time spent (in percentage of total) in deep sleep
timeInDeepZqPoints	The number of ZQ points accounting for deep sleep
timeInLight	The amount of time spent (in minutes) in light sleep
timeInLightPercentage	The amount of time spent (in percentage of total) in light sleep
timeInLightZqPoints	The number of ZQ points accounting for light sleep
timeInRem	The amount of time spent (in minutes) in Rem sleep
timeInRemPercentage	The amount of time spent (in percentage of total) in Rem sleep
timeInRemZqPoints	The number of ZQ points accounting for Rem sleep
timeInWake	The amount of time spent (in minutes) awake
timeInWakePercentage	The amount of time spent (in percentage of total) awake
timeInWakeZqPoints	The number of ZQ points accounting for being awake
timeToZ	The amount of time (in minutes) it took to fall asleep
totalZ	The total time asleep (in minutes)
totalZZqPoints	The number of ZQ points accounting for Total Z
zq	The overall ZQ score for this sleep period
alarmReason	The AlarmReason value describes why the alarm rang
alarmRingIndex	The index in the sleep graph which the alarm rang
dayFeel	The feel score for the day
sleepGraph	This SleepStage value repeats multiple times to describe a sleep graph.
sleepGraphStartTime	A ZeoDateTime object describing the start time for the graph
sleepStealerScore	The overall score for any sleep stealers. -1 means no data.
wakeWindowEndIndex	If smartwake is being used, indicates the index of the end of the wake window/td>
wakeWindowShow	A boolean field, valid values are true or false
wakeWindowStartIndex	If smartwake is being used, indicates the index of the start of the wake window

The ZeoDateTime object contains the following attributes and fields:

ZeoDateTime Fields
Name	Description
year	The 4-digit year.
month	The numeric month of a calendar year
day	The numeric day of a calendar month
hour	The numeric hour of a 24-hour day
minute	The minute of the hour
second	The second of the minute

The ZeoDate object contains the following attributes and fields:

ZeoDate Fields
Name	Description
day	The numeric day of a calendar month
month	The numeric month of a calendar year
year	The 4-digit year.

The AlarmReason ENUM object contains the following values:

AlarmReason values
Name	Description
REM_TO_NON_REM_TRANSITION	SmartWake detected REM to non-REM transition and rang alarm.
NON_REM_TO_REM_TRANSITION	SmartWake detected non-REM to REM transition and rang alarm.
WAKE	SmartWake detected wake and rang alarm.
DEEP_RISING	SmartWake detected sleep depth rising and rang alarm.
END_OF_WAKE_WINDOW	Set alarm time was reached. SmartWake may or may not be active.
NO_ALARM	Alarm did not ring.

The SleepStatsGrouping ENUM object contains the following values:

SleepStatsGrouping values
Name	Description
COMBINED	If using date range: This takes all records within the specified inclusive date range and average them all together to a single averaged result If using by count: take the number of daily records specified and average them
DAILY	Stats averaged over each day
WEEKLY	Stats averaged over each week
MONTHLY	Stats averaged over each month

The SleepStage ENUM object contains the following values:

SleepStage values
Name	Description
UNDEFINED	Represents a time block where no data is available.
WAKE	Represents a time block where the subject was awake.
REM	Represents a time block where the subject was in REM sleep.
LIGHT	Represents a time block where the subject was in LIGHT sleep.
DEEP	Represents a time block where the subject was in DEEP sleep.

Status codes

Code	Description
0	Operation was successfull
1	General Error (Unknown)
2	Parameter not provided or in incorrect format
3	No account exists
4	No account exists for session
5	An API Key is required
6	API Key does not match caller domain.
7	API Key does not exist.
8	API called too many times.

getLatestSleepStats

Returns the SleepStats (grouped by day) with the latest date on record for the current user.

Parameters

Response

Example

Parameters

Required	Name	Type	Description
required	key	string	The API key of the API consumer.

Each response contains the following attributes:

Response Attributes
Name	Description
status	A status code, useful for determining success of the call. See status codes table.
versionApi	An versionApi (Attribute), informing the caller which version of the API is being used
versionBuild	An versionBuild (Attribute), informing the caller which build of the API is being used
reqId	The reqId identifies the request (reserved for later use)
rspId	The rspId identifies the response (reserved for later use)

Each response contains the following fields:

Response fields
Name	Description
name	The name tells the caller which function was called.
sleepStats	A SleepStats object

The SleepStats object contains the following objects, attributes and fields:

SleepStats Fields
Name	Description
awakenings	The number of times the individual woke up during the period
awakeningsZqPoints	The number of ZQ points due to awakenings
bedTime	A ZeoDateTime object describing the bed time
grouping	The SleepStatsGrouping Enum describing the method in which the data was averaged
morningFeel	An integer from 1-5 describing how the user felt that morning (1=bad,5=great!)
riseTime	A ZeoDateTime object describing the rise time
startDate	A ZeoDate object describing the start date for the SleepStats object
timeInDeep	The amount of time spent (in minutes) in deep sleep
timeInDeepPercentage	The amount of time spent (in percentage of total) in deep sleep
timeInDeepZqPoints	The number of ZQ points accounting for deep sleep
timeInLight	The amount of time spent (in minutes) in light sleep
timeInLightPercentage	The amount of time spent (in percentage of total) in light sleep
timeInLightZqPoints	The number of ZQ points accounting for light sleep
timeInRem	The amount of time spent (in minutes) in Rem sleep
timeInRemPercentage	The amount of time spent (in percentage of total) in Rem sleep
timeInRemZqPoints	The number of ZQ points accounting for Rem sleep
timeInWake	The amount of time spent (in minutes) awake
timeInWakePercentage	The amount of time spent (in percentage of total) awake
timeInWakeZqPoints	The number of ZQ points accounting for being awake
timeToZ	The amount of time (in minutes) it took to fall asleep
totalZ	The total time asleep (in minutes)
totalZZqPoints	The number of ZQ points accounting for Total Z
zq	The overall ZQ score for this sleep period

The ZeoDateTime object contains the following attributes and fields:

ZeoDateTime Fields
Name	Description
year	The 4-digit year.
month	The numeric month of a calendar year
day	The numeric day of a calendar month
hour	The numeric hour of a 24-hour day
minute	The minute of the hour
second	The second of the minute

The ZeoDate object contains the following attributes and fields:

ZeoDate Fields
Name	Description
day	The numeric day of a calendar month
month	The numeric month of a calendar year
year	The 4-digit year.

The SleepStatsGrouping ENUM object contains the following values:

SleepStatsGrouping values
Name	Description
COMBINED	If using date range: This takes all records within the specified inclusive date range and average them all together to a single averaged result If using by count: take the number of daily records specified and average them
DAILY	Stats averaged over each day
WEEKLY	Stats averaged over each week
MONTHLY	Stats averaged over each month

Status codes

Code	Description
0	Operation was successfull
1	General Error (Unknown)
2	Parameter not provided or in incorrect format
3	No account exists
4	No account exists for session
5	An API Key is required
6	API Key does not match caller domain.
7	API Key does not exist.
8	API called too many times.

getLatestSleepRecord

Returns the SleepRecord with the latest date on record for the current user.

Parameters

Response

Example

Parameters

Required	Name	Type	Description
required	key	string	The API key of the API consumer.

Each response contains the following attributes:

Response Attributes
Name	Description
status	A status code, useful for determining success of the call. See status codes table.
versionApi	An versionApi (Attribute), informing the caller which version of the API is being used
versionBuild	An versionBuild (Attribute), informing the caller which build of the API is being used
reqId	The reqId identifies the request (reserved for later use)
rspId	The rspId identifies the response (reserved for later use)

Each response contains the following fields:

Response fields
Name	Description
name	The name tells the caller which function was called.
sleepRecord	A SleepRecord object

The SleepRecord object contains the following objects, attributes and fields:

SleepRecord Fields
Name	Description
awakenings	The number of times the individual woke up during the period
awakeningsZqPoints	The number of ZQ points due to awakenings
bedTime	A ZeoDateTime object describing the bed time
grouping	The SleepStatsGrouping Enum describing the method in which the data was averaged
morningFeel	An integer from 1-5 describing how the user felt that morning (1=bad,5=great!)
riseTime	A ZeoDateTime object describing the rise time
startDate	A ZeoDate object describing the start date for the SleepStats object
timeInDeep	The amount of time spent (in minutes) in deep sleep
timeInDeepPercentage	The amount of time spent (in percentage of total) in deep sleep
timeInDeepZqPoints	The number of ZQ points accounting for deep sleep
timeInLight	The amount of time spent (in minutes) in light sleep
timeInLightPercentage	The amount of time spent (in percentage of total) in light sleep
timeInLightZqPoints	The number of ZQ points accounting for light sleep
timeInRem	The amount of time spent (in minutes) in Rem sleep
timeInRemPercentage	The amount of time spent (in percentage of total) in Rem sleep
timeInRemZqPoints	The number of ZQ points accounting for Rem sleep
timeInWake	The amount of time spent (in minutes) awake
timeInWakePercentage	The amount of time spent (in percentage of total) awake
timeInWakeZqPoints	The number of ZQ points accounting for being awake
timeToZ	The amount of time (in minutes) it took to fall asleep
totalZ	The total time asleep (in minutes)
totalZZqPoints	The number of ZQ points accounting for Total Z
zq	The overall ZQ score for this sleep period
alarmReason	The AlarmReason value describes why the alarm rang
alarmRingIndex	The index in the sleep graph which the alarm rang
dayFeel	The feel score for the day
sleepGraph	This SleepStage value repeats multiple times to describe a sleep graph.
sleepGraphStartTime	A ZeoDateTime object describing the start time for the graph
sleepStealerScore	The overall score for any sleep stealers. -1 means no data.
wakeWindowEndIndex	If smartwake is being used, indicates the index of the end of the wake window/td>
wakeWindowShow	A boolean field, valid values are true or false
wakeWindowStartIndex	If smartwake is being used, indicates the index of the start of the wake window

The ZeoDateTime object contains the following attributes and fields:

ZeoDateTime Fields
Name	Description
year	The 4-digit year.
month	The numeric month of a calendar year
day	The numeric day of a calendar month
hour	The numeric hour of a 24-hour day
minute	The minute of the hour
second	The second of the minute

The ZeoDate object contains the following attributes and fields:

ZeoDate Fields
Name	Description
day	The numeric day of a calendar month
month	The numeric month of a calendar year
year	The 4-digit year.

The AlarmReason ENUM object contains the following values:

AlarmReason values
Name	Description
REM_TO_NON_REM_TRANSITION	SmartWake detected REM to non-REM transition and rang alarm.
NON_REM_TO_REM_TRANSITION	SmartWake detected non-REM to REM transition and rang alarm.
WAKE	SmartWake detected wake and rang alarm.
DEEP_RISING	SmartWake detected sleep depth rising and rang alarm.
END_OF_WAKE_WINDOW	Set alarm time was reached. SmartWake may or may not be active.
NO_ALARM	Alarm did not ring.

The SleepStatsGrouping ENUM object contains the following values:

SleepStatsGrouping values
Name	Description
COMBINED	If using date range: This takes all records within the specified inclusive date range and average them all together to a single averaged result If using by count: take the number of daily records specified and average them
DAILY	Stats averaged over each day
WEEKLY	Stats averaged over each week
MONTHLY	Stats averaged over each month

The SleepStage ENUM object contains the following values:

SleepStage values
Name	Description
UNDEFINED	Represents a time block where no data is available.
WAKE	Represents a time block where the subject was awake.
REM	Represents a time block where the subject was in REM sleep.
LIGHT	Represents a time block where the subject was in LIGHT sleep.
DEEP	Represents a time block where the subject was in DEEP sleep.

Status codes

Code	Description
0	Operation was successfull
1	General Error (Unknown)
2	Parameter not provided or in incorrect format
3	No account exists
4	No account exists for session
5	An API Key is required
6	API Key does not match caller domain.
7	API Key does not exist.
8	API called too many times.

logout

This logs the user out of the API and closes the session.

Parameters

Response

Example

Parameters

Required	Name	Type	Description
optional	key	string	The API key of the API consumer.

Become a fan of Zeo and join the conversation

Join over 1,400 Zeo followers on Twitter

Read the latest blog posts from the Zeo Community

For every friend you refer who buys Zeo, you'll get $25!

Zeo Personal Sleep Coach is neither a medical device nor a medical program and is not intended for the diagnosis or treatment of sleep disorders. If you suspect that you may have a sleep disorder, consult your physician.

Zeo. The more you know, the better you sleep.™

Zeo Web API

Contents

Introduction

You can apply for a key here

API Basics

Request format

Response format

Identification and Authentication

Notification Service for Third Parties

Code Samples

You can download samples from here

Service Catalog

getOverallAverageZQScore

Parameters

Status codes

Example

getOverallAverageDayFeelScore

Parameters

Status codes

Example

getOverallAverageMorningFeelScore

Parameters

Status codes

Example

getOverallAverageSleepStealerScore

Parameters

Status codes

Example

getAllDatesWithSleepData

Parameters

Status codes

Example

getDatesWithSleepDataInRange

Parameters

Status codes

Example

getSleepStatsForDate

Parameters

Status codes

Example

getSleepRecordForDate

Parameters

Status codes

Example

getPreviousSleepStats

Parameters

Status codes

Example

getPreviousSleepRecord

Parameters

Status codes

Example

getNextSleepStats

Parameters

Status codes

Example

getNextSleepRecord

Parameters

Status codes

Example

getEarliestSleepStats

Parameters

Status codes

Example

getEarliestSleepRecord

Parameters

Status codes

Example

getLatestSleepStats

Parameters

Status codes

Example

getLatestSleepRecord

Parameters

Status codes

Example

logout

Parameters

Example