While this post is targeted at attendees of the September 2012 Quantified Self conference in Palo Alto, even if you’re not attending you still might find some useful Health Graph information and development tips.
Welcome Quantified Self attendees and hackers! You’re in for a great weekend of learning and networking. And hopefully plenty of fun!
Here are the sessions where I’ll be representing RunKeeper:
- “Hacking APIs” breakout session, Saturday 10:30AM – Beau Gunderson (@beaugunderson) of Singly and I will be discussing APIs for self quantification and hackery. We hope to have a lively discussion with you and each other, examining APIs for QS from every angle.
- RunKeeper & Health Graph office hour, Saturday 1:30PM – I’ll be available to discuss Health Graph development and answer any questions you may have.
I will also be attending as many of our partners’ sessions as I can, while hopefully having lots of time to share ideas and make new connections. Please contact me (@billday) if you’d like to get together at the conference.
To prepare for the conference, or begin using the Health Graph directly on your own, you should start by watching this high level overview of the Health Graph platform:
For a quick primer on developing with the Health Graph API, click through the more technical presentation below:
All Health Graph partners are required to follow the Health Graph API Policies.
You can access more technical details on the RESTful Health Graph API by clicking here. Experiment and prototype with the API using the Health Graph Developer’s Console (click here to load the console).
When you’re ready to start your app in earnest, visit the RunKeeper Partner page and click “Connect To Our API“. From there you can fill out the form to register your new Health Graph integrated app, service, or device.
Click here to learn about authorization removal callbacks before providing your callback URL on the form. If you will be reading data out of the Health Graph for accounts other than your own app registering account, you should also request Read permission on the form, being sure you give a detailed explanation of what you will do with that data once you’ve accessed it. Likewise, if you would like to ask users for permission to retain their Health Graph data across deauthorizations and/or edit health information for authorizing users, please request permission(s) on the form.
Need some inspiration to get your developer juices flowing? Check out some of the applications built and deployed using the Health Graph API, available from the RunKeeper Apps page (click here). You can also access an archive of third party libraries, wrappers, and bindings which might make your Health Graph API-based development easier by clicking here. And there’s more information on how app and library partners are taking advantage of the Health Graph via our Health Graph partner profiles series on the blog.
One more tip: Click here to learn how to export your own user data from the Health Graph; useful for programmable self hacks as well as backups and parsing your data to re-upload into a test account via the Health Graph API.
Now that you know how to use the Health Graph, go build something great!
Recently added fields include:
source– string added to Fitness Activities, Background Activities, Nutrition, Sleep, Diabetes Measurements, and Weight portions of the Health Graph API; this provides the name of the application that last modified the given activity or measurement; see documentation for details.
is_live– boolean added to Fitness Activities to indicate whether the activity is currently being tracked via RunKeeper Live; note that this field will report ‘
false‘ until at least one GPS point for the Live activity is received (this should occur immediately upon beginning the Live activity, but may be delayed up to several seconds if it takes longer than normal for GPS hardware to acquire a sufficient GPS signal).
userID– integer added to each team member entry from Street Team
GET /teamresponse to allow developers to more easily access team member account details (assuming member has authorized the calling app).
- past activities are now available in a summary form that is more conducive to bandwidth-constrained environments; search for ‘summary’ in the Fitness Activities docs to learn more.
- blood markers – a number of additional markers have been added to the General Measurements portion of the Health Graph API; for the complete list of what’s now available, please refer to documentation for General Measurements and Diabetes portions of the API.
Thanks to everyone that provided feedback on our previous expansion of user data export, we have pushed an update so that it now also supports:
- Heart rate information in exported activity GPX files
- Start/stop in GPX for all activities where the user paused and then resumed their activity
Heart rate information is included with each GPS data point via
gpxtpx:hr tags, while each pause/resume results in a new
One question we often get from developers new to the Health Graph platform is “How can I create test data?”. Here are some ways you can get up and running quickly.
After you request developer Health Graph access, you have automatic read access to any data in your developer account. You can take advantage of that by using various free Health Graph apps to add data to your account. For example, you can record or manually enter:
- Fitness activities using our RunKeeper app (iOS | Android | Windows Phone).
- Sleep information with GKSleep (web app) or Sleepy (Android).
- Nutrition information via GKNutrition (web app).
- Weight data using Weighty (iOS) or the “Body Measurements” update widget on the lower left of your RunKeeper homepage (web app).
Another way to add data to your developer account is to use an existing non-development account and Street Team tagging.
You can copy existing fitness activity data into your developer account by:
- Logging into an existing non-development account containing fitness activities.
- Adding your developer account as a Street Team member in your non-development account; you’ll need to make the request from the latter and then approve it from the former.
- For each activity you wish to copy from your non-development account into your developer account, tag the developer account from that activity’s page; this copies the activity data into your developer account.
- Optional: When you’re done tagging and copying data, you can remove the tags while in your developer account, then remove your non-development account from your developer account Street Team, to sever the linkages but keep the copied data.
One more option: You can export an existing user’s data (click here for details) then parse that data and write it back into your own developer account via the Health Graph API. In fact, doing so is very instructive as it requires you to explore several different aspects of the Health Graph platform.
The above options should give you plenty of ways to get test data together for your application. I hope this helps and happy health hacking!
We recently made a change to developer Health Graph read access.
Developers can now read data from their own app registering account, the one they listed when they submitted their app registration in the Partner portal, without needing to apply for special Read permissions. This automatic read permission lets one begin using the full Health Graph API immediately against their own data.
To make certain everyone is clear on what the change enables, let’s define “registering account” as the account under which an app is registered. Then as far as permissions are concerned, the new rules for Health Graph data requests are as follows:
- A read request for the registering account succeeds
- A read request for a non-registering account succeeds if and only if Special API Read permissions have been requested and granted
- A write request succeeds
Note: To read from any other Health Graph account, apps still need to make a request for and be granted the Special API Read permissions. Also Health Graph API Policies remain unchanged.
We hope this helps you get going faster on new Health Graph projects.
We have updated the Health Graph user data export capability so that it now supports exporting all activities and all measurements from the user’s account. This includes data written into the Health Graph by partner apps, services, and devices in addition to RunKeeper’s app. Note that for activities which have an associated GPS track, those tracks are exported as well.
For users, this means they can export and backup all their health and fitness data whenever they like. For developers and self hackers, this also means they can download and manipulate their own user data as they see fit. We’ve had a number of requests for the latter, and we’re very glad to answer them!
More details on how the export works:
Initiate the export by logging in to your RunKeeper.com account settings page, scrolling to the bottom, and clicking on the “Export Data” link. Alternatively you can directly access the export form here: http://runkeeper.com/exportDataForm
You then select starting and ending dates for the data you’d like to export, answer the captcha, and submit your request. Assuming you filled out the form correctly, once you click “Export Data” you’ll see a response indicating that your data is being packaged and will be delivered in a few minutes. You will then receive an email containing a link to download your data in a ZIP archive.
The ZIP contains
measurements.csv CSV files containing activity and point measurement data, respectively. You can use any standard CSV tools and libraries to read and modify these files, including loading them into spreadsheets such as the freely available Google Docs (examples below).
GPS tracks are included as GPS eXchange Format (GPX) files, one file for each activity with an associated a track. Please note that the GPX filename corresponding to any given activity is included at the end of that activity’s
cardioActivities.csv row, too. You can step through the CSV file until you find an activity of interest, then use the GPX filename field to jump out to that particular activity’s track.
Here’s an abridged example of a GPX file containing GPS track data for the first entry in the example activities from above:
Another thing to note: The export does not include photos that the user might have uploaded during RunKeeper recorded activities. Our team discussed including photos versus not, and decided not to for the following reason: We believe including them would be redundant at best (since those photos also remained on the user’s phone at upload time) and could lead to very large ZIP file size and download time at worst.
Your feedback on any and all aspects of this would be appreciated. You can reach us via:
- A response to my data export post in the Health Graph discussion group
- A message to our Health Graph Twitter (@HealthGraphAPI), Facebook, or Google+ accounts
- If you find something you believe is a bug, or you have a new user data export-related feature you would like to request, please visit our Support site to search for your issue; if it’s not already filed, please consider filing it.
If we’ve missed anything critical, please let us know.