Validating tracked versus manual fitness activities using the Health Graph API

One question we receive fairly often from Health Graph (@healthgraphapi) partners is how to validate that fitness activities (runs, walks, bike rides, etc.) read out of the Health Graph platform were GPS-tracked versus manually entered by the user. Rewards partners a la Earndit and GymPact, corporate wellness providers like Virgin HealthMiles, and forward-thinking brands are often keen to differentiate between tracked versus manually entered activities as part of their programs’ anti-fraud efforts.

So how do you tell the difference between GPS and manual activities?

Each item in the Fitness Activity feed has ‘source‘, ‘entry_mode‘, and ‘has_path‘ fields. These let you determine whether the activity was originally submitted as a GPS-tracked activity. For example, a RunKeeper (@runkeeper) mobile app GPS-tracked run should have values of “RunKeeper“, “API“, and “true” for the aforementioned fields, respectively.

Health Graph fitness activity documentation

If you are interested in including GPS-tracked sources from other Health Graph partners’ activity trackers, you can include them in your ‘source‘ filtering. In addition, if you need to differentiate by type of activity (i.e. running, walking, cycling, etc.) you can use the ‘type‘ field.

Using these fields should let you skip any activities for which the user simply entered statistics, or originally entered the route map (path) via the Web. For more details on these fields and their usage, please refer to the Health Graph fitness activities documentation, especially the array structures section.

Caveat: The only reliable way to verify whether a user has subsequently edited the map associated with a saved GPS-tracked activity is to manually check each point’s ‘type‘ (a value of “manual” means it has been edited). For efficiency’s sake, we don’t save that information anywhere else in the Health Graph platform and we retrieve points only when full data for the activity is requested. That said, we have found that most users do not edit maps after the fact.

Bill Day (@billday) is Platform Evangelist & PM for RunKeeper where he helps developers learn about and use the Health Graph.

RunKeeper hackathon recap

What happens when you give the RunKeeper crew two days to let imaginations run wild? A whole lot of awesome, I tell ya!

Our product team is always five steps ahead in terms of planning awesome updates to the app, but in the process, it seems each developer has some sort of other dream RunKeeper project they’d love work on if given the time. We decided to set two work days aside for engineers (and others throughout the company) to try to bring those to reality.

The community had lots of interesting ideas on what would make it into our first-ever hackathon, and many of the resulting hacks lined up with your hopes! There was a simple start widget for the home and lock screens on Android, much-improved data visualizations for your fitness reports, refreshed technology for GPS tracking, in-app strength training tracking, a pretty new website, and some ridiculously fun and motivating audio cues. And a few other things that are internal and top secret—for now :).

We’re cranking hard to turn some of these hacks into actual RunKeeper updates and features, so stay tuned! And in the meantime, the pictures and videos below are definitely worth (more than a) thousand words.

Kicking off some collaboration


Jacked Jim gears up for his commercial debut in the RoidKeeper strength training promotional video


This team gave a whole new meaning to the term long hours. (And garnished some awesome prizes in the process)


Makers of the aforementioned awesome audio cues hack demo their goods


A little hack to get some more real-time insights into our community


Working to build the perfect GPS algorithm


And this video really speaks to the need for that widget hack

One of our many rocking trophies


Cross-posted from the RunKeeper blog.

GymPact pays you for exercising with RunKeeper

GymPact (@gympact) from Health Graph (@healthgraphapi) partner Pact helps motivate your exercise with cold, hard cash. With GymPact‘s Health Graph integration, qualifying RunKeeper tracked running, walking, and biking activities can be turned into money in your pocket. Read on to learn how GymPact motivates healthy behavior using the Health Graph.

Bill Day: Please tell us about yourself and Pact.
Yifan Zhang: A classic dormroom to startup story, I co-founded Pact with my Harvard classmate Geoff Oberhofer. We were both fascinated by a behavioral economics principle that people are motivated much more by loss than rewards.

We decided to first tackle the specific problem of getting people to the gym more often, and launched GymPact on January 1st, 2012.

BD: What is the “elevator pitch” for why someone should use GymPact?
YZ: Do you pay for an expensive gym membership but can never find the time to use it? GymPact is an iPhone app that lets you earn cash rewards for checking in at the gym, paid for by non-exercisers!

You can make a Pact to work out, choose how much money you’ll put on the line to motivate you, and earn cash when you meet your Pact. Our over 45,000 GymPact users are 90% successful at getting to the gym on committed days.

BD: How did you get started using the Health Graph API?
YZ: Ever since we launched, our users have asked to count outdoor activities (runs, walks, bike rides) toward their Pact. The Health Graph platform has allowed us to easily partner with awesome products like RunKeeper to give our users a feature they wanted.

BD: How is using the Health Graph benefiting your business?
YZ: We announced our integration with the Health Graph a few weeks before the launch, and the response was overwhelming! We had over 1,000 people sign up for our beta list on the first day, and tons more likes/RT’s on social media.

BD: Which portions of the Health Graph API do you use, and why?
YZ: Right now, we are pulling RunKeeper GPS-tracked activities from the API so that we can automatically count them toward GymPacter’s Pacts.

BD: What do you like about the Health Graph? What would you like to see changed?
YZ: The integration was so simple! There were very few bugs, which allowed us to focus on the product and experience rather than the engineering challenges of integration. We see no changes needed for the current version of what we’re doing.

BD: If you could request any new feature from the Health Graph, what would it be? How would you use it?
YZ: We would like to have verified activities marked specifically, since we would like to pull data from other Health Graph-integrated apps as well as RunKeeper.

BD: Can you share any future plans for Pact? What’s coming next that your users will be excited about? Does the Health Graph play a role in that, and if so, how?
YZ: One big thing is that we have an Android app now in private beta! You can sign up for it on our homepage or here. Also, we’re looking to partner with other health apps to incentivize verified healthy activities. The Health Graph is huge for making those partnerships simple!

Bill Day (@billday) is Platform Evangelist for RunKeeper where he helps developers learn about and use the Health Graph.

Health Graph API additions

We’ve made several recent additions to the Health Graph API (@healthgraphapi) based upon partner feedback and requests.

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 /team response 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.

Please let us know if you have any questions about these API updates by leaving a comment here or on this Health Graph discussion group thread (click here to access).

Bill Day (@billday) is Platform Evangelist for RunKeeper where he helps developers learn about and use the Health Graph.

Convert GPX normalized time to local time

We sometimes get questions about how to figure out the local time for fitness activities exported as part of a user data export.

Time and date information included in exported GPX files are normalized to universal time. See below for an example showing normalized times such as 2012-03-24T06:12:45Z.

Here are the steps you would follow to convert from universal time to local time:

  1. Read the normalized date and time out of one or more GPX export file track points
  2. Use the latitude and longitude in those track points to derive local time zone offset(s)
  3. Convert the universal time values in the GPX files into local time using the offset(s)

That’s all there is to it!

Bill Day (@billday) is Platform Evangelist for RunKeeper where he helps developers learn about and use the Health Graph.

Support causes with Fitgiver and the Health Graph

The winner of our AngelHack prize for best use of the Health Graph (@healthgraphapi) was Fitgiver (@fitgiver) with their app enabling Health Graph users to raise money for the causes they love by doing the things they love to do anyway. One of Fitgiver’s founders, R. Colin Kennedy (@rcolinkennedy), took time out of a very busy schedule to answer a few questions for us. Take his experiences as inspiration to build great things at a hackathon near you, too!

Bill Day: Please tell us about yourself and your team.

R. Colin Kennedy: The Fitgiver team comes from a variety of backgrounds – some of us work at startups, some of us have a background in big business, and another is staff at MIT – but what unites us the opportunity that Fitgiver presents to create a meaningful impact.

BD: How did you get involved with AngelHack? And why did you decide to try out the Health Graph API?

CK: Well, a few of us ride bicycles together and had been kicking this around for a while. AngelHack was a great opportunity to move things to the next level. We had each individually done hackathons and Startup Weekends on other projects, and AngelHack promised a higher level of visibility, great prizes, and uniqueness because it was the first time running it in Boston.

The Fitgiver concept was tied to the Health Graph from its very inception. When we ride together, several of us use RunKeeper to track our activities. We knew that creates a data stream that is accessible and we thought we’d try and put it to use for causes we care about.

The beauty of it is that once users connect Fitgiver with their Health Graph account, they don’t actually have to do anything differently than they already were: Just use RunKeeper like normal, and we pull the data. [Editor’s note: This should work with other Health Graph-based fitness activity tracking apps as well.]

BD: What is the “elevator pitch” for why someone should use Fitgiver?

CK: There are at least two different answers to that question.

First, our elevator pitch is that Fitgiver connects people and the causes they care about with organizations that want to sponsor them.

Second, users should consider Fitgiver because if they’re already going for a run or ride anyway, why not do some good while they’re at it?

BD: How is using the Health Graph benefiting Fitgiver? Which portions of the Health Graph API do you use, and why?

CK: The Health Graph makes data collection super easy. Currently, we’re using the workouts people track with RunKeeper. This is great because we also get the geo data, which we can use to verify that these workouts were real workouts, and at some point we’re thinking about localizing sponsorships so local businesses can sponsor local athletes. This really opens up a very powerful potential for both charities and small businesses to support people that are in their communities.

BD: What do you like about the Health Graph? What would you like to see changed?

CK: So far we’ve been really happy with the reliability and documentation with the API. It just works!

BD: Can you share any future plans for Fitgiver?

CK: We’re in talks with national health-related charities, and with sponsor companies that are looking like potential launch partners. Feedback has been so positive, we just have to keep going.

BD: Is there anything else we should know about your team or your application?

CK: We are all RunKeeper users and athletes, and have been so excited by the level of support that we’ve gotten from the RunKeeper team. Looking forward to furthering the partnership!

Bill Day (@billday) is Platform Evangelist for RunKeeper where he helps developers learn about and use the Health Graph.