Trends Endpoint

GET /v1/insights

get insights for user

• requires access token
• scopes: OAuthScope.INSIGHTS_READ

Raw request:

curl -H 'Authorization:Bearer 6.341a764a866b4f138dbe5591ca72b9bd' 'https://dev-api.hello.is/v1/insights/'

Return value: a list of insights cards

  {
    "id": 2,
    "title": "Lately",
    "message": "[placeholder] Your sleep has improved since you started working out.\n\nGood job!",
    "category": "WORKOUT",
    "created_utc": 1419295500000,
    "account_id": 984
  },
  {
    "id": 8,
    "title": "Last night",
    "message": "[placeholder] Your sleep was more agitated than usual.",
    "category": "SLEEP_QUALITY",
    "created_utc": 1419295500000,
    "account_id": 984
  },
  {
    "id": 9,
    "title": "This week",
    "message": "[placeholder] You've been sleeping one hour less on average.",
    "category": "SLEEP_DURATION",
    "created_utc": 1419295500000,
    "account_id": 984
  }
]

GET /v1/insights/trends/list

Get a list of parameters for available graphs.

• requires access token
• scopes: OAuthScope.INSIGHTS_READ

Raw request:

curl -H 'Authorization:Bearer 6.341a764a866b4f138dbe5591ca72b9bd' 'https://dev-api.hello.is/v1/insights/trends/list'

Return value: a list of available data_type and time_period pair

[
  {
    "data_type": "sleep_duration",
    "time_period": "DOW"
  },
  {
    "data_type": "sleep_score",
    "time_period": "DOW"
  },
  {
    "data_type": "sleep_score",
    "time_period": "1W"
  },
  {
    "data_type": "sleep_score",
    "time_period": "2W"
  },
  {
    "data_type": "sleep_score",
    "time_period": "1M"
  },
  {
    "data_type": "sleep_score",
    "time_period": "3M"
  },
  {
    "data_type": "sleep_score",
    "time_period": "ALL"
  }
]

GET /v1/insights/trends/all?option=blah

Get the graph data for default list:

1. sleep score by day of week
2. sleep score over time (default: all data up to 365 days)
3. sleep duration by day of week

• requires access token
• scopes: OAuthScope.INSIGHTS_READ

Query parameters:

• option can be one of these (1W, 2W, 1M, 3M, ALL) for amount of data in the sleep-score over time graph. If option is not specified, the ALL option is the default.

Raw request:

curl -H 'Authorization:Bearer 6.341a764a866b4f138dbe5591ca72b9bd' 'https://dev-api.hello.is/v1/insights/trends/all'

Return value: a list of graphs. And empty list for "data_points" means that we don't have graph data yet.

[
  {
    "title": "SLEEP SCORE BY DAY OF WEEK",
    "options": [],
    "data_type": "SLEEP_SCORE",
    "graph_type": "HISTOGRAM",
    "time_period": "DOW",
    "data_points": [
      {
        "datetime": 0,
        "y_value": 0.0,
        "x_value": "MO",
        "offset_millis": 0,
        "data_label": "OK"
      },
      {
        "datetime": 0,
        "y_value": 0.0,
        "x_value": "TU",
        "offset_millis": 0,
        "data_label": "OK"
      },
      {
        "datetime": 0,
        "y_value": 0.0,
        "x_value": "WE",
        "offset_millis": 0,
        "data_label": "OK"
      },
      {
        "datetime": 0,
        "y_value": 0.0,
        "x_value": "TH",
        "offset_millis": 0,
        "data_label": "OK"
      },
      {
        "datetime": 0,
        "y_value": 82.0,
        "x_value": "FR",
        "offset_millis": 0,
        "data_label": "GOOD"
      },
      {
        "datetime": 0,
        "y_value": 82.0,
        "x_value": "SA",
        "offset_millis": 0,
        "data_label": "GOOD"
      },
      {
        "datetime": 0,
        "y_value": 0.0,
        "x_value": "SU",
        "offset_millis": 0,
        "data_label": "OK"
      }
    ]
  },
  {
    "title": "SLEEP DURATION BY DAY OF WEEK",
    "options": [],
    "data_type": "SLEEP_DURATION",
    "graph_type": "HISTOGRAM",
    "time_period": "DOW",
    "data_points": []
  },
  {
    "title": "SLEEP SCORE OVER TIME",
    "options": [
      "1W",
      "2W",
      "1M",
      "3M",
      "ALL"
    ],
    "data_type": "SLEEP_SCORE",
    "graph_type": "TIME_SERIES_LINE",
    "time_period": "ALL",
    "data_points": [
      {
        "datetime": 1415318400000,
        "y_value": 84.0,
        "x_value": "",
        "offset_millis": -28800000,
        "data_label": "GOOD"
      },
      {
        "datetime": 1415404800000,
        "y_value": 84.0,
        "x_value": "",
        "offset_millis": -28800000,
        "data_label": "GOOD"
      },
      {
        "datetime": 1415491200000,
        "y_value": 82.0,
        "x_value": "",
        "offset_millis": -28800000,
        "data_label": "GOOD"
      }, ......
    ]
  }
]

There are two types of graphs at the moment.

####Day of Week Graph

• graph_type = HISTOGRAM
• data_type = SLEEP SCORE or SLEEP DURATION
• time_period = DOW
• options = empty list, there's none
• data_points will have 7 values where
  • x_value is a string with one of these values (MO, TU, WE, TH, FR, SA, SU).
  • y_value the day of week average (float).
  • datetime is irrelevant, will have value of 0.
  • offset_millis is irrelevant, set to 0.

####Over Time Graph This is basically a time-series.

• graph_type = TIME_SERIES_LINE
• data_type = SLEEP SCORE (for now)
• time_period will be one of these: (1W, 2W, 1M, 3M, ALL)
• options = ["1W", "2W", "1M", "3M", "ALL"]
• data_points will have 7 values where
  • x_value = ""
  • y_value the sleep score value in float
  • datetime is the UTC timestamp
  • offset_millis is the offset required to transform datetime to local time

If data_points contain empty list, that means we haven't got enough data for the user.

GET /v1/insights/trends/graph

• requires access token
• scopes: OAuthScope.INSIGHTS_READ

Path variables:

• data_type (sleep_score or sleep_duration)
• time_period (DOW for day of week graphs, [1W, 2W, 1M, 3M, ALL] for time-series graph)

Raw request:

curl -H 'Authorization:Bearer 6.341a764a866b4f138dbe5591ca72b9bd' 'https://dev-api.hello.is/v1/insights/trends/graph?data_type=sleep_score&time_period=1W'

Return Value: one graph object

{
  "title": "SLEEP SCORE OVER TIME",
  "options": [
    "1W",
    "2W",
    "1M",
    "3M",
    "ALL"
  ],
  "data_type": "SLEEP_SCORE",
  "graph_type": "TIME_SERIES_LINE",
  "time_period": "1W",
  "data_points": [
    {
      "datetime": 1418688000000,
      "y_value": 80.0,
      "x_value": "",
      "offset_millis": -28800000,
      "data_label": "OK"
    },
    {
      "datetime": 1418774400000,
      "y_value": 82.0,
      "x_value": "",
      "offset_millis": -28800000,
      "data_label": "GOOD"
    },
    {
      "datetime": 1418860800000,
      "y_value": 81.0,
      "x_value": "",
      "offset_millis": -28800000,
      "data_label": "GOOD"
    },
    {
      "datetime": 1418947200000,
      "y_value": 82.0,
      "x_value": "",
      "offset_millis": -28800000,
      "data_label": "GOOD"
    },
    {
      "datetime": 1419033600000,
      "y_value": 82.0,
      "x_value": "",
      "offset_millis": -28800000,
      "data_label": "GOOD"
    }
  ]
}