Customizing Charts

❗️

Deprecated feature

The current iteration of the Chart API will continue to be available for paying customers but will not be actively developed. Thank you for your understanding.

706

Once you have added a chart to your page, customizing charts from the Chart API can be easily done via query parameters added to the iframe URL. The guide below will outline all available options, chart types, and styling tips.

📘

See the Chart API Overview for more information on authenticating and adding a chart to your page.

Query Parameters

There are numerous query parameters that you can use to customize the aesthetic and data for each graph. Chart API parameters universal to all chart types are listed in this section and all other non-universal parameters are listed along with each chart's description in subsequent sections of this page.

📘

Standard Query Parameters

All standard query parameters used for the Data API are also valid when rendering charts. Please refer to the standard query parameters (including date ranges) as detailed on the Patterns and Conventions page of the documentation.

ParameterValueDescription
chart_tokenChart Token[Required] Chart Token for the relevant Human API user. (See Chart API Overview for information on obtaining a chart token)
yData ParameterThe value that you would like plotted on the graph as it relates to the Human API JSON data object.
See the API Reference for each data type.

(e.g. "steps", "calories", "duration", etc...)
Note: must be a numerical value
daysNumber of days
( max 50 )
Returns a graph with data for the specified number of days ending with the current day.

This calculates start_time and end_time date range parameters, which can alternatively be supplied explicitly for an end date that is not the current day
colorHex or CSS Color

(omit # for hex)
Add a custom color theme to your graph.

(e.g. "lightgreen" and "90EE90" are equivalent)
Defaults to "steelblue" if not specified.
unitUnit for plotted Y ValueTime = [milliseconds, seconds, minutes, hours]
Distance = [millimeters, centimeters,meters,kilometers, inches, feet, miles]
Mass = [kilograms, lbs]

Retains default object value if not specified

🚧

Max Records Displayed

By default, all charts will display a maximum of 50 records. To display up to 500, ensure you set a higher limit parameter.

External Styling

When placing a chart on your page, there are only three external formatting items that need to be defined: border, width & height.

We recommend setting border: none so that the chart appears like a native part of your application. Additionally, all charts are dynamically sized based on the defined height and width of the iframe, so it is important to set these properties as well.

A basic implementation of the CSS styling properties might look like this:

iframe {
  border: none;
  width: 100%;
  height: 300px;
}

Chart Types

Below are all possible chart types with examples. For your reference, here are the data types available for the Chart API:

Bar Chart

/v1/human/activities/summaries?chart_token=demo&color=lightgreen&start_date=2015-09-01&end_date=2015-09-28&type=bar&y=distance
Available For:
  • Periodic Resources
  • Discrete Resources
Summary

Shows a bar graph with detail tooltip on hover.

Periodic & Discrete Resources

Append type=bar query parameter to any endpoint.

Additional Parameters

ParameterValueDescription
typeChart TypeSet to bar to render bar graph. Defaults to line graph.

Line Graph

/v1/human/blood_pressure/readings?chart_token=demo&color=tomato
Available For:
  • Periodic Resources
  • Discrete Resources
Summary

Shows a line graph with details and data points on hover.

Periodic Resources
Use any Periodic Resource endpoint.

Discrete Resources
Use any Discrete Resource endpoint with /readings.

Additional Parameters

ParameterValueDescription
smoothingSmoothing MethodApply a line smoothing method to your graph.

Possible values :
[linear, monotone, cardinal, basis]
(no smoothing <-> high smoothing)

Note: basis does not show data point and detail text on hover

Latest Value

/v1/human/blood_pressure?chart_token=demo&color=lightblue
Available For:
  • Discrete Resources
Summary

Shows the latest value retrieved for a particular data type along with the source and time elapsed.

Discrete Resources

Use any query for a discrete resource without /readings

Goal Gauge

/v1/human/activities/summaries?chart_token=demo&color=orange&type=gauge&goal=12000&start_date=2015-10-25&end_date=2015-10-25
Available For:
  • Periodic Resources
Summary

Shows a gauge representing how close the user is to a specific goal. (percentage shown on hover)

Use any query for a discrete or periodic resource and set type=gauge and the goal parameter.

For today's totals, simply use days=1

ParameterValueDescription
goalIntegerThe goal value represented as the 100% mark of the gauge.

Chart API Explorer