Object types and terminology

Users

This data is useful for customising the display of user data to the user's preferences. Use timezone to show times in the correct time zone for the user. Use the imperial_* flags to know which values to show in imperial units.

{
    "username": "josh",
    "first_name": "Josh",
    "last_name": "Sharp",
    "avatar": "https://exist.io/media/avatars/josh_1.png",
    "timezone": "Australia/Melbourne",
    "local_time": "2022-05-13T16:55:54.302963+10:00",
    "imperial_distance": false,
    "imperial_weight": false,
    "imperial_energy": false,
    "imperial_liquid": false,
    "imperial_temperature": false,
    "trial": false,
    "delinquent": false
}

Attributes

This is our name for data points or individual numbers a user can track about themselves. These are tracked at a single day granularity — there's no per-hour or -minute data. Attributes can be string types but are usually quantifiable, i.e. integers or floats. The value_type field reflects this type.

An attribute has many values, one for each day that it has been tracked. If requested, the values property will contain an array of date/value pairs.

An attribute has a user-facing label, which may be any string and include emoji, and a name, which is a simple ASCII identifier that you'll use when referring to the attribute for things like updates. These are not guaranteed to be the same.

If there is no data for a particular date, this will be reflected with a null value — you should expect to receive a list of results containing every single day, rather than days without data being omitted.

All datetimes in values are in UTC unless otherwise specified, and should have the user's timezone applied to create a local TZ-aware datetime. All dates are local to the user.

Values are always stored internally and returned in metric units. Each user object contains imperial_* flags which must be respected when formatting values for the user, i.e. if imperial_distance is true, a steps_distance value must be converted from kilometres to miles.

Attributes have a priority integer which is used for sorting (in ascending order). Attributes belong to groups which have a label and a priority, also used for sorting. Clients should display attributes in these groups when displaying multiple attributes. Groups are currently fairly broad and may change as we add more supported attributes.

manual attributes are those which are not automatically filled with data from a supported integration, but instead have manual entry UI provided within our official clients. If you're creating a client that will provide data for attributes, you want manual to be false.

Attributes can be "templated", meaning they take their name and other values from an attribute template we provide. In this case, the attribute's name will be known, as it matches the template. See also list of attribute templates and attribute value types.

{
    "group": {
        "name": "activity",
        "label": "Activity",
        "priority": 1
    },
    "template": "steps",
    "name": "steps",
    "label": "Steps",
    "priority": 1,
    "manual": false,
    "active": true,
    "value_type": 0,
    "value_type_description": "Integer",
    "service": {
        "name": "googlefit",
        "label": "Google Fit"
    },
    "values": [
        {
            "date": "2022-05-13",
            "value": 1337
        }
    ]
}

Correlations

Correlations are a measure of the relationship between two variables. A positive correlation implies that as one variable increases (its values get higher), so does the other. A negative correlation implies that as one variable increases, the other decreases. We present these to users as a way to explain past trends, and use them to predict future behaviour.

Correlation values vary between -1 and +1 with 0 implying no correlation. Correlations of -1 or +1 imply an exact linear relationship.

P-values are a way of determining confidence in the result. A value lower than 0.05 is generally considered "statistically significant". We provide a user-friendly stars integer which maps to the P-value, where 5 stars indicates a value well below 0.05.

We create simple English sentences to represent each possible correlation as a combination of attributes.

We're also careful to represent these as correlations only, not as one attribute directly causing a change in the other, and we ask that you do the same. Correlation is not causation. There may be many hidden factors which underlie the relationship between two attributes. It is up to the user to determine the cause.

Correlations are generated weekly on Sundays.

{
  "date": "2022-05-08",
  "period": 364,
  "offset": 0,
  "attribute": "steps",
  "attribute2": "walk",
  "value": 0.6754596120404917,
  "p": 7.928064702293852e-50,
  "percentage": 67.54596120404916,
  "stars": 5,
  "second_person": "you get more steps when you tag 'walk' more.",
  "second_person_elements": [
    "you get more steps",
    "when",
    "you tag 'walk' more"
  ],
  "attribute_category": null,
  "strength_description": "Nearly always go together",
  "stars_description": "Certain to be related",
  "description": null,
  "occurrence": null,
  "rating": {
    "positive": true,
    "rating_type": 50,
    "rating": "Useful"
  }
}

attribute_category is used to distinguish "sub-correlations", that is, correlations for a subset of this attribute's data. For example, we may find a correlation between events in a specific calendar and productive_min — in this case, attribute_category would contain the name of the specific calendar.

description and occurrence fields are filled when both attributes are templated and we understand this relationship. For example, for the productive_min and tracks positive correlation, occurrence will be "Very common" and description will provide some further information about why music helps us be more productive.

rating provides a user-submitted rating object on the value of the correlation.

Examples

"You are more productive when you listen to music more."

(55% strength / 5 stars / P 0.007)

In this case the value is 0.55, and this is a positive correlation — when one value (tracks played) increases, so does the other (time spent productively).

"You are less active when it's a warmer day."

(25% strength / 5 stars / P 0.02 )

In this case the value is -0.25, and this is a negative correlation — when one value (max temp) increases, the other decreases (time active).

Insights

Insights are interesting events found within the user's data. These are not triggered by the user but generated automatically if the values for an attribute fit an insight type's criteria. Typically these fall into a few categories: day-level events, for example, yesterday was the highest or lowest steps value in however many days; and week and month-level events, like summaries of total steps walked for the month. If an insight is relevant to a specific day it will contain a target_date value.

Insights have a priority where 1 is highest and means real-time, 2 is day-level, 3 is week, and 4 is month.

HTML and text output is provided.

{
    "created": "2022-05-13T08:17:30+01:00",
    "target_date": "2022-05-13",
    "type": {
        "name": "dow_tracks",
        "period": 1,
        "priority": 1,
        "attribute": {
            "name": "tracks",
            "label": "Tracks played",
                "group": {
                "name": "media",
                "label": "Media",
                "priority": 7
            },
            "priority": 1,
            "value_type": 0,
            "value_type_description": "Integer"
        }
    },
    "html": "<div class=\"secondary\">You listen to more music on a Friday.</div>\r\n<div class=\"num-label\">&quot;Kurt Vile&quot; has been on high rotation.</div>",
    "text": "You listen to more music on a Friday.\r\n\"Kurt Vile\" has been on high rotation."
},

Averages

Averages are generated weekly and are the basis of our goal system. In our clients, the average is used to create the "end value" of the attribute's progress bar for a single day — meaning each day, users are being shown their progress relative to their usual behaviour. We break down averages by day of the week but also record the overall average. As we keep historical data this allows us to plot "rolling averages" showing changes in attribute values. The data set for finding the average is always the last 60 days' data.

Note: these are actually medians, but we use "average" as it's simpler to explain to users. Please also use this terminology.

{
    "user_attribute": "sleep",
    "date": "2022-05-08",
    "overall": 399,
    "monday": 382,
    "tuesday": 425,
    "wednesday": 401,
    "thursday": 394,
    "friday": 376,
    "saturday": 406,
    "sunday": 419
}

Clients and services

We use client to refer an application with OAuth2 client credentials. A client which writes data to attributes is termed a service. Where we use the term integration, this means a service with a first-party integration with Exist.

List of attribute templates

All the "official" attributes we currently support. Templated attributes are treated differently because we "understand" them — they receive their own insights, individual wording for correlations, and so on. You should prefer them over custom attributes where possible. Attributes that are "templated" take their name and value type from the template.

The group an attribute belongs to may change in future, but attribute names should be considered stable.

Remember all data for templated attributes must be sent, and is stored and returned, in metric units. Imperial conversion should occur when rendering as required.

See attribute definition.

Name	Group	Value type description	Value type
`steps`	Activity	Integer	`0`
`steps_active_min`	Activity	Period (minutes as integer)	`3`
`steps_elevation`	Activity	Float (km)	`1`
`floors`	Activity	Integer	`0`
`steps_distance`	Activity	Float (km)	`1`
`stand_hours`	Activity	Integer	`0`
`cycle_min`	Activity	Period (minutes as integer)	`3`
`cycle_distance`	Activity	Float (km)	`1`
`active_energy`	Activity	Float (kJ)	`1`
`workouts`	Workouts	Integer	`0`
`workouts_min`	Workouts	Period (minutes as integer)	`3`
`workouts_distance`	Workouts	Float (km)	`1`
`productive_min`	Productivity	Period (minutes as integer)	`3`
`neutral_min`	Productivity	Period (minutes as integer)	`3`
`distracting_min`	Productivity	Period (minutes as integer)	`3`
`commits`	Productivity	Integer	`0`
`tasks_completed`	Productivity	Integer	`0`
`words_written`	Productivity	Integer	`0`
`emails_sent`	Productivity	Integer	`0`
`emails_received`	Productivity	Integer	`0`
`pomodoros_min`	Productivity	Period (minutes as integer)	`3`
`keystrokes`	Productivity	Period (minutes as integer)	`3`
`coffees`	Food and drink	Integer	`0`
`alcoholic_drinks`	Food and drink	Integer	`0`
`energy`	Food and drink	Float (kJ)	`1`
`water`	Food and drink	Integer (ml)	`0`
`carbohydrates`	Food and drink	Float (g)	`1`
`fat`	Food and drink	Float (g)	`1`
`fibre`	Food and drink	Float (g)	`1`
`protein`	Food and drink	Float (g)	`1`
`sugar`	Food and drink	Float (g)	`1`
`sodium`	Food and drink	Float (mg)	`1`
`cholesterol`	Food and drink	Float (mg)	`1`
`caffeine`	Food and drink	Float (mg)	`1`
`money_spent`	Finance	Float (user's local currency unit)	`1`
`mood`	Mood	Integer scale (between 1 and 9)	`8`
`mood_note`	Mood	String (max 1000 characters)	`2`
`energy_level`	Mood	Integer scale (between 1 and 9)	`8`
`stress_level`	Mood	Integer scale (between 1 and 9)	`8`
`sleep`	Sleep	Period (minutes as integer)	`3`
`time_in_bed`	Sleep	Period (minutes as integer)	`3`
`sleep_light`	Sleep	Period (minutes as integer)	`3`
`sleep_deep`	Sleep	Period (minutes as integer)	`3`
`sleep_rem`	Sleep	Period (minutes as integer)	`3`
`sleep_start`	Sleep	Time of day (minutes from midday as integer)	`6`
`sleep_end`	Sleep	Time of day (minutes from midnight as integer)	`4`
`sleep_awakenings`	Sleep	Integer	`0`
`events`	Events	Integer	`0`
`events_duration`	Events	Period (minutes as integer)	`3`
`weight`	Health	Float (kg)	`1`
`body_fat`	Health	Float (percentage, 0.0 to 1.0)	`5`
`lean_mass`	Health	Float (kg)	`1`
`heartrate`	Health	Integer	`0`
`heartrate_max`	Health	Integer	`0`
`heartrate_variability`	Health	Integer	`0`
`heartrate_resting`	Health	Integer	`0`
`meditation_min`	Health	Period (minutes as integer)	`3`
`menstrual_flow`	Health	Integer (`0`=none, `1`=spotting, `2`=light, `3`=medium, `4`=heavy)	`0`
`sexual_activity`	Health	Integer	`0`
`checkins`	Location	Integer	`0`
`location`	Location	String (`"lat,lng"` format where `lat` and `lng` are floats)	`2`
`tracks`	Media	Integer	`0`
`articles_read`	Media	Integer	`0`
`pages_read`	Media	Integer	`0`
`mobile_screen_min`	Media	Period (minutes as integer)	`3`
`gaming_min`	Media	Period (minutes as integer)	`3`
`tv_min`	Media	Period (minutes as integer)	`3`
`facebook_posts`	Social	Integer	`0`
`facebook_comments`	Social	Integer	`0`
`facebook_reactions`	Social	Integer	`0`
`tweets`	Twitter	Integer	`0`
`twitter_mentions`	Twitter	Integer	`0`
`twitter_username`	Twitter	String	`2`
`weather_temp_max`	Weather	Float (degrees Celsius)	`1`
`weather_temp_min`	Weather	Float (degrees Celsius)	`1`
`weather_precipitation`	Weather	Float (inches of water per hour)	`1`
`weather_cloud_cover`	Weather	Float (percentage of sky covered, 0.0 to 1.0)	`5`
`weather_wind_speed`	Weather	Float (km/hr)	`1`
`weather_summary`	Weather	String	`2`
`weather_icon`	Weather	String (name of icon best representing weather values)	`2`
`day_length`	Weather	Period (minutes as integer)	`3`

Attribute value types

These are the allowed types of values an attribute can store. Each attribute has a single, fixed value type.

Note: value type 6 (minutes from midday) is reserved for attribute templates. New attributes cannot be created via the API with this value type.

Value type description	Value type
Integer quantity	`0`
Decimal	`1`
String	`2`
Duration (minutes as integer)	`3`
Time of day (minutes from midnight as integer)	`4`
Percentage (float, 0.0 to 1.0)	`5`
Time of day (minutes from midday as integer)	`6`
Boolean	`7`
Scale (1-9 as integer)	`8`

Custom tags

Custom tags are booleans type attributes represented as integers (0 or 1) within the custom group, and are user-defined so unable to be listed here. Examples include tags like meditation, tired, and sex.

To correctly get all tags for a day, collect all attributes:

with a value type of 7;
within the custom group;
with a value of 1.

A value of 1 represents the "tagged" state, 0 or null meaning the tag was not used for that day.

Tags have internal names like any other attribute, but remember to display them using their label field.