Patterns and Conventions

Example queries

Human API lets you query a user's health data with a Bearer token authorization header. For details on how to authorize users and retrieve these tokens please click here.

Bearer token:

curl -H "Authorization: Bearer demo" https://api.humanapi.co/v1/human

📘
The demo access token will serve demo user data. Replace it with a valid accessToken to get data for that specific user.

Media types

Human API uses JSON (JavaScript Object Notation) for all payloads. To accommodate for this:

Set the Accept Header to application/json when querying data.
Set the Content-Type Header to application/json when sending data.

API versions

Different versions of Human API can be used by specifying the version number in the url, i.e. /v1:

https://api.humanapi.co/[version]/human
https://api.humanapi.co/v1/human

Query options

The standard query options for Human API are as described in the table below. These parameters make it easier for you to implement smart synchronization for your application. For instance, by using the updated_since parameter you only retrieve the data that was changed or added since the specified time.

Parameter	Description
`limit`	The max number of records to return in one query. Default is 50. Maximum is 500 if set.
`offset`	The index of the first record to return. Default is 0
`created_since`	Returns records that are created after the specified date.
`updated_since`	Returns records that are updated after the specified date.
`created_before`	Returns records that are created before the specified date.
`updated_before`	Returns records that are updated before the specified date.
`source`	Returns filtered data from a specific source. (Use the source name, all lowercase no spaces as found on records. e.g. - `googlefit`, `ihealth`, `myfitnesspal`, etc.)

📘
All dates are in UTC date format: YYYYMMDDTHHmmssZ

Date ranges

In addition to the parameters listed above, you can also query by a date range. These parameters must be used together.

Parameter	Description
`start_date`	The oldest date to retrieve. Format YYYY-MM-DD
`end_date`	The most recent date to retrieve. Format YYYY-MM-DD

Data types

Discrete Measurements
A discrete measurement is a unit of data that is captured at a point in time and has a timestamp, a value, and a type. A measurement can also have an optional location or other meta data. To retrieve the discrete measurements you can follow the following pattern:

To retrieve the latest reading:

/v1/human/[type]

To retrieve a reading by ID:

/v1/human/[type]/{id}

To retrieve the list of readings:

/v1/human/[type]/readings

To retrieve a list of readings for a specific date:

/v1/human/[type]/readings/daily/{YYYY-MM-DD}

Periodic data

Periodic data, unlike discrete data, always has a start and end date. The data types that fall into this category are activities, sleeps, and locations. This type of data can be retrieved as a list of objects or as a summary object for a specific date or time period.

To retrieve a list of periodic data objects:

/v1/human/[type]

To retrieve a single object by ID:

/v1/human/[type]/{id}

To retrieve a list of objects for a specific date:

/v1/human/[type]/daily/{YYYY-MM-DD}

To retrieve the latest summary objects:

/v1/human/[type]/summaries

To retrieve a summary object for a specific date:

/v1/human/[type]/summaries/{YYYY-MM-DD}

To retrieve a summary object by Id:

/v1/human/[type]/summaries/{id}

Medical data

Medical data includes any data from the Medical API endpoints.

To retrieve a list of periodic data objects:

/v1/human/[type]

To retrieve a single object by ID:

/v1/human/[type]/{id}

Pagination conventions

To make it easier to retrieve all the data for a user you can iterate through their historical data using the Link Header and, optionally, the X-Total-Count Header. The Link Header contains the first, prev, next, and last links that will help you easily iterate through all the records available for a query. The Link Header follows the RFC5988 standard.

For example, if you query a user with the following parameters:

/activities?start_date=2013-01-01&limit=50&offset=100

Your response headers would return like this:

Link:   https://api.humanapi.co/v1/human/activities?&limit=50&start_date=2013-01-01&offset=50; 
rel="prev",
   https://api.humanapi.co/v1/human/activities?limit=50&start_date=2013-01-01&offset=8450; 
rel="last",
   https://api.humanapi.co/v1/human/activities?limit=50&start_date=2013-01-01&offset=0; 
rel="first"

There is also a total count for the query stored in the X-Total-Count Header:

X-Total-Count: 8490