📘

Syncing User Data

Batch Queries are one way to keep you user's information up-to-date. For best practices, see Keeping User Data Up-to-date.

📘

Only available for Wellness

Batch Queries are currently not available for the Medical API

To make your data synchronization tasks more efficient you can take advantage of the batch query capabilities of the Application level API . This allows you to synchronize the data for all of the users of your app in one query per data type. You need to use the updated_since query parameter and keep track of the last query time so that you can retrieve only the data that has been updated since the last time you queried.

Endpoints

Base URL

https://api.humanapi.co/v1

Individual Endpoints

/apps/:clientId/users/activities
/apps/:clientId/users/activities/summaries
/apps/:clientId/users/heart_rates
/apps/:clientId/users/heart_rate/summaries
/apps/:clientId/users/bmis
/apps/:clientId/users/body_fats
/apps/:clientId/users/heights
/apps/:clientId/users/weights
/apps/:clientId/users/blood_pressures
/apps/:clientId/users/blood_glucoses
/apps/:clientId/users/blood_oxygens
/apps/:clientId/users/sleeps
/apps/:clientId/users/sleeps/summaries
/apps/:clientId/users/genetic_traits
/apps/:clientId/users/locations
/apps/:clientId/users/food/meals

These endpoints replicate those available for the individual user queries. The payload data model is the same for individual and batch queries, except the batch query results return data for multiple users so you need to parse the data accordingly.

Although we recommend using Notifications in tandem with batch queries, in some cases developers rely solely on batch queries for data synchronization. If you do so, it is recommended that you run the queries frequently to avoid accumulating a lot of data resulting in huge payloads and longer response times. A good role of thumb is to run your query as often as required to avoid having to paginate your queries.

🚧

Updated_since is Required

Do not perform regular batch queries without the updated_since query parameter. By supplying updated_since with your last query time, you can ensure that your queries are quick and efficient.

• If updated_since is not specified, you will only get 24 hours of updated data. Additionally, the maximum amount of time that can be queried by batch will be 31 days.

• To pull all of your application’s data, you will need to use a combination of updated_since and updated_before to pull data for time intervals no greater than 31 days per query.

Authentication

Authentication for Batch Queries is the same as that for the Application API. Instead of user accessTokens, which authorize access to an individual user's data, you will need to use your App Key to authorize the request on behalf of your full application. The App Key should be sent sent as the username of your request with the password left blank. See the example below for what this looks like:

Example GET Query

Using curl command line:

curl -X GET -H 'Accept: application/json' \
    -u e7db255f4828e1d482743eba04faacb945ab7ca8: \
https://api.humanapi.co/v1/apps/1d129c20acf6fcef9be0b067cc7859d872ed5ade/users/activities?updated_since=20130925T120000Z

An example activity payload is shown below. It is the same format as the standard endpoint except each record can have a different humanId:

[
  {
    id: "52867cbfde3155565f000b01",
    userId: "51cc7cb31a154bf215000002",
    humanId: "7eddd553c81b8de9ac271bc21f50e32e",
    startTime: "2013-11-01T17:27:00.346Z",
    endTime: "2013-11-01T18:27:11.346Z",
    type: "walking",
    source: "runkeeper",
    duration: 3611,
    distance: 1251,
    steps: 2689,
    calories: 482,
    timeZone: "America/Los_Angeles",
    sourceData: {},
    timeSeries: {},
    createdAt: "2013-11-01T17:27:00.346Z",
    updatedAt: "2013-11-01T17:27:00.346Z"
  },
  {
    id: "52867cbfde3155565f000b02",
    userId: "538b9d3a9b1e35be7302607e",
    humanId: "55d894b33a942540ac4b93dfd493eef1",
    startTime: "2014-05-31T16:18:19.000Z",
    endTime: "2014-05-31T19:00:27.000Z",
    type: "cycling",
    source: "strava",
    duration: 9728,
    distance: 45468.6,
    steps: 0,
    calories: 0,
    sourceData: {
      maxHeartrate: 196,
      averageHeartrate: 145,
      maxSpeed: 17.3,
      mapId: "a147785724",
      movingTime: 7782,
      type: "Ride"
    },
    createdAt: "2014-05-31T19:03:32.032Z",
    updatedAt: "2014-05-31T19:03:32.032Z"
  },
  {
    id: "52867cbfde3155565f000b03",
    userId: "538029c700850beb2601c578",
    humanId: "3b9e7162aea8280b3661f25784b3e9ba",
    startTime: "2014-05-28T20:04:02.000Z",
    endTime: "2014-05-29T00:00:00.000Z",
    type: "walking",
    source: "mapmyfitness",
    duration: 0,
    distance: 178636.74,
    steps: 0,
    calories: 1916,
    sourceData: { },
    createdAt: "2014-05-31T00:21:09.386Z",
    updatedAt: "2014-05-31T00:21:09.386Z"
  }
]

📘

Pagination

The default number of results returned per query is 50 and the max is 500 by setting a higher limit. You can paginate through the rest of the results based on the documentation here.