Google Health Data API Reference Guide

This document provides detailed reference documentation for the Google Health data API.

Contents

Overview

Google Health uses a subset of the CCR (Continuity of Care Record) to transport health data. The companion to this document defines the subset of the CCR (Continuity of Care Record), an XML standard for health data exchange, along with the Google Data API protocol to transport medical records.

For extensive documentation on CCR, see:

• CCR Standard Resource Site
• CCR (Continuity of Care Record) wiki entry, with links to other resources
• The CCR specification is available for purchase from ASTM International.

Back to top

Audience

This document is intended for programmers who want to write applications that can interact with Google Health.

This document assumes that you are familiar with the CCR. It also assumes that you understand the general ideas behind the Google Data APIs protocol.

Back to top

Namespaces

The health/kind namespace is a Google Data API namespace used to identify that an atom:entry in the feed is a health item. It is identified by the URL: http://schemas.google.com/health/kinds.

Type of element/query	Namespace
Profile feed entries	http://schemas.google.com/health/kinds#profile
Register feed entries	http://schemas.google.com/health/kinds#register
Google Data CCR category queries	http://schemas.google.com/health/ccr
Google Data label category queries	http://schemas.google.com/health/item

Back to top

Health feed types

AuthSub feeds

Register feed

An entry of the register feed represents a single notice in the user's notices panel. The register feed is used to collect data from sources external to Google. Individual posts to this feed are known as notices. Notices can contain plain text (including certain XHTML elements), or a CCR document, or both (but always at most one CCR document). For example, notices might be sent to remind users to pick up a prescription, or they might contain lab results in the CCR format.

Note: Using AuthSub, this is the only feed that can be used to write data into a profile.

The URL of the AuthSub register feed is:

https://www.google.com/health/feeds/register/default

Profile feed

A profile feed is a set of entries that collectively describe a user's medical conditions, medications, test results, and other health record information. It contains both user-entered data and data sent by third parties. If the user has granted access to his/her profile data, you can retrieve that data by sending an HTTP GET to this feed.

The URL of the AuthSub profile feed is:

https://www.google.com/health/feeds/profile/default

ClientLogin feeds

ClientLogin has its own versions of the profile and register feeds. The contents of the feeds are semantically equivalent to the AuthSub versions.

The URL of the ClientLogin register feed is:

https://www.google.com/health/feeds/register/ui/profileID

The URL of the ClientLogin profile feed is:

https://www.google.com/health/feeds/profile/ui/profileID

For example, performing an HTTP GET with https://www.google.com/health/feeds/register/ui/tyi6YUSFYU_9x retrieves a list of notices for the profile with ID tyi6YUSFYU_9x. You can discover a user's profile IDs by querying the profile/list feed.

Profile List feed

Since ClientLogin requires a profile ID with each of its feeds, services will likely want to query this feed first in order to select the appropriate profile. The profile list feed returns Atom entries corresponding each profile in the user's Google Health account. The profile ID is returned in the Atom <content> and the profile name in the <title> element.

The URL of the profile list feed is:

https://www.google.com/health/feeds/profile/list

Here is an example entry:

...
<entry>
  <id>https://www.google.com/health/feeds/profile/list/tyi6YUSFYU_9x</id>
  <title type='text'>Joe Smith's Profile</title>
  <content type='text'>tyi6YUSFYU_9x</content>
  <link rel='self' type='application/atom+xml' href='https://www.google.com/health/feeds/profile/list/tyi6YUSFYU_9x' />
  <link rel='edit' type='application/atom+xml' href='https://www.google.com/health/feeds/profile/list/tyi6YUSFYU_9x' />
  <author>
    <name>joe.smith@gmail.com</name>
  </author>
</entry>
...

Back to top

Authentication

The most common way to access the Health feeds is by using AuthSub; however, ClientLogin authentication is also supported for use with desktop applications.

The following table summarizes supported operations by feed and authentication type.

Note: The Feed URL prefix is https://www.google.com/health/feeds/ with all the feeds below.

Feed URL Suffix	AuthSub	ClientLogin
register/default	POST
register/ui/profileID		GET POST PUT DELETE
profile/default	GET
profile/ui/profileID		GET POST PUT DELETE
profile/list		GET

With AuthSub, you bind the authentication to a specific user/profile combination. Hence using AuthSub, you know that the /default feed points to the profile associated with the current AuthSub token. Conversely, a ClientLogin authentication token is not bound to a particular profile. Therefore, you must pass the ID of the profile as part of the feed URL in any requests. You can get the profile ID by querying the Profile List feed.

Using AuthSub

Clients that connect via AuthSub can read the profile feed if the user has granted permissions, and can post notices to the register feed. If such notices are in CCR format, the contents will be automatically reconciled into the user's profile.

Clients that connect via AuthSub cannot update or delete anything from the profile feed or the register feed, and they also cannot read from the register feed.

Troubleshooting AuthSub requests

Domain seems to not be registered.

Authsub domain logins are case sensitive. Please verify that you are using the exact spelling.

403 Error (unauthorized).

• Make sure you registered the right scope. In particular, be sure to register the https://www.google.com/health/feeds scope and not the insecure version (http).
• Make sure you are requesting the right access privileges for the target profile (privileges can be write-only or write and read).

My feeds are empty.

Make sure the profile is visible, has items in it, and that you are accessing the right profile with your authsub access. A user can have multiple profiles. You can check that you are using the right profile by opening the application located at https://www.google.com/health and select application ==> settings.

Permissions for tokens change to the last issued token.

This is the expected behavior. The access permissions are set per target domain (the service URL) and profile, not per actual token. Permission values for older tokens get overwritten when you request a new token.

Using ClientLogin

For clients that access the feeds via ClientLogin authentication, all feeds support GET, POST, PUT, and DELETE.

If you use ClientLogin to insert a notice into the register feed, the contents of your posted entry are automatically reconciled. However, updates are not automatically reconciled.

Back to top

Health query parameters reference

Google Health supports the following subset of Google Data API query parameters:

• q (only supported for the register feed)
• start-index
• max-results
• published-min
• published-max
• updated-min
• updated-max

Google Health also supports the following additional parameters:

Parameter	Meaning	Notes
/category	Category filter. Refer to the Google Data documentation for usage information and category queries for specifics about the Google Health implementation of this parameter.	For example: -/medication/{http://schemas.google.com/health/item}Lipitor&max-results=10 will return the first 10 entries for the medication Lipitor.
digest=true	May only be used on the profile feed. Returns content as an aggregation of all entries into a single CCR entry, which contains the collection of enclosed entries. Refer to Digest parameter for usage information. The default value is digest=false. You may set this to true or false.	For example: https://www.google.com/health/feeds/profile/default?digest=true will return a digest version of the profile feed.
grouped=true	Returns a count of results per group. The default value is grouped=false. You may set this to true or false.	For example: ?grouped=true&max-results-in-group=50 will return the first 50 records for each group. ?grouped=true&max-results-in-group=1 will return the top record for each group (which, incidentally, would be the profile summary query.)
max-results-group	Specifies the maximum number of groups to be retrieved. Must be an integer value greater than zero. This parameter is only valid if grouped=true.	For example: /feeds/profile/default/-medications?grouped=true&max-results-in-group=2max-results-group=10 will return the top 10 medications with up to 2 items each. /feeds/profile/default/-medications?grouped=true&max-results-in-group=2&max-results-group=10&max-results=3 will return the top 10 medications with up to 2 items each, but no more than 3 total results.
max-results-in-group	Specifies the maximum number of records to be retrieved from each group. The limits that you specify with this parameter apply to all groups. Must be an integer value greater than zero. This parameter is only valid if grouped=true.	For example: /feeds/profile/default/-medications?grouped=true&max-results-in-group=2max-results-group=10 will return the top 10 medications with up to 2 items each. /feeds/profile/default/-medications?grouped=true&max-results-in-group=2&max-results-group=10&max-results=3 will return the top 10 medications with up to 2 items each, but no more than 3 total results.
start-index-group	Retrieves only items whose group ranking is at least start-index-group. This should be set to a 1-based index of the first group to be retrieved. The range is applied per category. This parameter is only valid if grouped=true.	For example: ?grouped=true&start-index-group=43 will return items from groups 44 and higher.
start-index-in-group	Is a 1-based index of the records to be retrieved from each group This parameter is only valid if grouped=true.	For example: ?grouped=true&start-index-in-group=2 will skip the first item of each group.

Category queries

Google Health recognizes two types of categories: CCR categories and item categories. A CCR category defines sets such as medications, conditions, etc. Item categories are more specific in that they define groups of item names within a CCR category (e.g. "Ibuprofen" within the Medication CCR category). An item category restriction must be used in conjuction with a CCR category restriction, a CCR category restriction however can be issued by itself.

CCR categories

The CCR categories are represented by the http://schemas.google.com/health/ccr namespace and include the following case-insensitive categories. These are linked to the relevant descriptions in the CCR Reference chapter.

• Labtest. This maps to Results
• Medication
• Condition
• VitalSigns
• Procedure
• Immunization
• Allergy. This maps to Alerts
• Demographics. This maps to Actor, VitalSigns, FunctionalStatus and SocialHistory.

http://schemas.google.com/health/ccr is the default namespace for all queries. For example:

-/medication/{http://schemas.google.com/health/item}Lipitor?max-results=10 will return the first 10 entries for the medication Lipitor. This is exactly the same query as -/{http://schemas.google.com/health/ccr}medication/{http://schemas.google.com/health/item}Lipitor?max-results=10

Item categories

The http://schemas.google.com/health/item namespace indicates the group name. It is used to categorize entry titles. An entry title is usually equivalent to the record name.

The group name is the name of the item. For example, for a medication, it would be the name of the medication, such as Lipitor. Each group can contain multiple records that describe interactions with that item.

For a category query to contain a http://schemas.google.com/health/item namespaced category, it also must contain a http://schemas.google.com/health/ccr (or empty) namespaced category. Filtering for an item can only be requested in conjunction with ccr-category filtering.

Each entry returned by the server will contain the URI of the associated category.

Digest parameter

The standard profile feed returns one entry per piece of medical information, each of which is represented in a CCR document. Sometimes clients want to receive the complete medical information about a user in a single CCR document.

If the digest=true parameter is set on the profile feed, the profile feed is returned in digest format. A digest formatted feed contains at most one entry: the CCR document which is the aggregation of all profile entries of the underlying profile feed. Category queries are also supported in conjunction with the digest format.

The digest=true parameter can be called in conjunction with the following parameters, in which case the semantics of those parameters are applied to the enclosed entries.

Parameter	Meaning	Notes
max-results	Specifies the maximum number of profile entries to be retrieved, which gets aggregated into the digest entry.	For any service that has a default max-results value (to limit default feed size), you can specify a very large number if you want to receive the entire feed.
published-min, published-max	Specifies the bounds on the profile entry publication date, which get aggregated into the digest entry	Use the RFC 3339 timestamp format. For example: 2005-08-09T10:57:00-08:00. The lower bound is inclusive, whereas the upper bound is exclusive. For the digest entry, published-min and published-max are computed as the min/max over all enclosed entries.
start-index	Is a 1-based index of the first profile entry to be retrieved, which gets aggregated into the digest entry.	Note that this isn't a general cursoring mechanism. If you first send a query with ?start-index=1&max-results=10 and then send another query with ?start-index=11&max-results=10, the service cannot guarantee that the results will be equivalent to ?start-index=1&max-results=20, because insertions and deletions could have taken place in between the two queries.
updated-min, updated-max	Specifies the bounds on the profile entry update date, which get aggregated into the digest entry.	Use the RFC 3339 timestamp format. For example: 2005-08-09T10:57:00-08:00. The lower bound is inclusive, whereas the upper bound is exclusive. For the digest entry, updated-min and updated-max are computed over all update timestamps of entries in the profile (including deleted entries, which are not included in the digest). Therefore an update timestamp might be newer than any of the enclosed entries.

In order for the feed to be paginated, we support the following query syntax: ?digest=true&start-index=x&max-results=y. This will paginate the results within the profile entry set before merging them into a single CCR.

Category queries are also supported for usage with the digest parameter and follow the same syntax described above; e.g. /feeds/profile/default/-/medication?digest=true will return a CCR document containing all of your medications.

The CCR schema allows for repeated elements for all relevant profile entries. Author fields will be aggregated on the feed level; therefore the correlation between the author and the profile entry is not maintained. Thus, if you need the author fields, set digest=false.

Back to top

Health elements reference

For an explanation of all of the elements available in the Google Health API, refer to the Google CCR Reference.

Back to top