Important: This is an old version of this page. For the latest version, use the links in the left-side navbar.
This document provides detailed reference documentation for the Google Health data API.
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:
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.
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 API CCR category queries | http://schemas.google.com/health/ccr |
| Google Data API label category queries | http://schemas.google.com/health/item |
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
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 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.
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>
...
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.
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.
https://www.google.com/health/feeds scope and not the insecure version (http).https://www.google.com/health and select application ==> settings.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.
Google Health supports the following subset of Google Data API query parameters:
q (only supported for the register feed)start-indexmax-resultspublished-minpublished-maxupdated-minupdated-maxGoogle Health also supports the following additional parameters:
| Parameter | Meaning | Notes |
|---|---|---|
/category |
Category filter. Refer to the Google Data API documentation for usage information and category queries for specifics about the Google Health implementation of this parameter. |
For example:
|
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 |
For example:
|
grouped=true |
Returns a count of results per group. The default value is |
For example:
|
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 |
For example:
|
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 |
For example:
|
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 |
For example:
|
start-index-in-group |
Is a 1-based index of the records to be retrieved from each group This parameter is only valid if |
For example:
|
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.
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 ResultsMedicationConditionProcedureImmunizationAllergy. This maps to AlertsDemographics. 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
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.
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 |
|
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. |
|
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.
For an explanation of all of the elements available in the Google Health API, refer to the Google CCR Reference.