Using the Zeo Android API

There are a bunch of things that are not obvious from the documentation.  These are just notes on things I figured out while developing an app using their API.

To clarify terminology I’m using:

  • Short epoch – 30 seconds worth of sleep data.  The base hypnogram contains sleep stages that each represent a short epoch.
  • Long epoch – 5 minutes worth of sleep data which Zeo summarizes as one sleep stage regardless of the stages of the corresponding short epochs.  The display hypnogram contains sleep stages that each represent a long epoch.


  1. Though the base hypnogram contains a reading every 30 seconds, the headband only transmits these back to the phone every 5 minutes.  I’ve seen it transmit in smaller increments but I think this only happens upon certain events:
    1. Headband is docked/undocked
    2. Headband is on/off head
    3. Personally I’ve never seen SmartWake work, but I wouldn’t be surprised if the headband knew to transmit an update any time you move in and out of REM.  I haven’t actually seen this, but it just sounds like a reasonable possibility.
  2. The display hypnogram seems to always contain an even number of epochs.  So when there is only one long epoch of real data the display hypnogram will contain two elements, the second being a 0 for “undefined”.  When the next long epoch finishes, the second element will be updated with real data and the display hypnogram will still have two elements.
    1. This means if you want to know the most recent long epoch stage you cannot just take the last element.
  3. When a Sleep Record is “finalized” it has appeared that the undefined epochs get trimmed from the end of the display hypnogram but not the base hypnogram.  After a particular night of sleep I saw that the Sleep Record had continued to be updated long after I docked the headband (both hypnograms).  Eventually it did stop, and at that point the undefined epochs were removed from the end of the display hypnogram.  The same did not happen to the base hypnogram
  4. When a smaller increment of short epochs is transmitted as described in #1, it does not write a corresponding incomplete long epoch at that point.  The long epoch will be added to the display hypnogram when it is finished.