My favorites | English | Sign in

Google Health Data API

Frequently Asked Questions

Contents

Introduction

  1. What is Google Health?

    Google Health is the software platform within Google that receives and publishes personal health information. The platform uses the Atom Publishing Protocol to receive data, apply coding heuristics, and allow for managing one or more user profile.

  2. How can I create and access a Google Health account?

    You can create a Google Health account through Google Health or by using a linked application. You can interact directly with Google Health through the Google Health web site. The web site provides full access to create, view, and edit profiles, and to view notices. You can also interact with Google Health through linked applications that use the API.

  3. What are the central ideas to the platform?

    The Register Feed and Profile Feed are the most important concepts in Google Health Data API.

    • The register feed allows your application to post new data (notices) to a user's profile. At this time, only data can be added to a profile (using an HTTP POST) and cannot be updated or deleted once posted. CCR information that is included in the posted notice is auto-reconciled into the corresponding profile.
    • Using the profile feed, your application can perform an HTTP GET to retrieve the user's entire Google Health Profile. Information cannot be changed using this feed.

  4. What programming languages are supported by the API?

    Google Health is a web service so you are able to use any language that can perform the four HTTP methods (GET/POST/PUT/DELTE). Google Health leverages the Google Data APIs, which have client libraries in Java, .NET, PHP, Python, Objective-C, and JavaScript. At this time, only the Java and .NET libraries support Google Health. See the Google Data APIs Client Libraries document for more information.

Back to top

Basics

  1. What is the relationship between the Google Data APIs and Google Health?

    Google Data is the preferred way for applications to interface programmatically with the Google Health platform. Google Data eases application integration by encapsulating and hiding the AtomPub specification and implementation.

  2. How do I submit notices and create profiles?

    There are two ways to interact with the Google Health platform. Your application may use one of the client libraries or interact directly with Atom feeds to add to notices and read from profiles. You are also able to use the web-based UI to manipulate your Google Health data. You will need to construct a CCR in order to send your data to a user's profile.

  3. How can my application interact with Google Health?

    Depending on the permissions the user grants to the application, a linked application account can:

    • Add notices using the register feed. (permission=0)
    • Add notices and view a user's profile. (permission=1)

    The permissions are granted during the linking process when obtaining an AuthSub token. Users can use the Google platform to revoke permissions granted to a linked application at any time.

  4. Our organization is a HIPAA covered entity and we want to send patient data to Google Health. What steps should we to take?

    Normally you would need to agree to a consent form. Google has provided an Sample Authorization Form (Authorization for Health Care Providers) draft consent form. You should have your legal team modify this form to meet your needs.

  5. Best Practices

    Refer to the Developer Best Practices guide for more information.

Back to top

Authentication via AuthSub

  1. What is the AuthSub URL used when requesting a token for Google Health?

    https://www.google.com/health/authsub

  2. What is the "next" parameter?

    The "next" parameter is the URL that Google Health will redirect the user to after he/she grants access to thier profile data. This should be a page of your web application.

  3. What is the "scope" parameter?

    The "scope" parameter is a URL defining the scope of the associated AuthSub token. For Google Health, this is "https://www.google.com/health/feeds".

  4. What is the "session" parameter?

    The "session" parameter determines whether the temporary AuthSub token returned in the current request will be exchanged for a long lived "session" token. In the case of Google Health, you must use session=1. Health requires the use of long-lived sesssion tokens.

  5. What is the "secure" parameter?

    The "secure" parameter specifies whether or not the current request is being signed with a private key. If it is set to "0", then a private key is not being used. If it is set to "1", then a private key is being used. Although you can use secure=0 in the h9 developer's sandbox, /health requires the use of secure tokens.

  6. What is the "permission" parameter?

    The "permission" parameter is a numeric value indicating the level of access that should be granted to a new AuthSub token. It can be either of the following values.

    • 0 = Add notices only.
    • 1 = Add notices and view the profile.

  7. How do I programatically interface with AuthSub?

    See AuthSub for Web applications

  8. Why can't I get an Google Health AuthSub Token using https://www.google.com/accounts/AuthSubRequest?

    Google Health uses its own AuthSub service at https://www.google.com/health/authsub. The Google Data client library does not create the correct URL for Google Health's AuthSub service. You should either edit the Google Data client library source code or replace the AuthSub part of the generated URL ("/accounts/AuthSubRequest") with the correct Google Health AuthSub service ("/health/authsub").

  9. How is the AuthSub process different for Google Health?

    Due to the granularity of permissions possible (create notices, and create notices and read profiles), the url used for AuthSub in the Google Health API is different than that used for other Google APIs. Refer to the Google Health Authsub process in the Google Health Developers discussion forum for more details.

  10. The permissions on my AuthSub token changed, but I didn't update that setting. What happened?

    Permissions for tokens change to the last issued token for the associated profile. The access right is set per target domain and profile, not per actual token. Permission values for older tokens will get overwritten.

  11. My long-term AuthSub session token was revoked, but I didn't explicitly revoke it. What happened?

    There is a limit to the number of AuthSub tokens that can be associated with a profile for each service provider. Creating a new token once that limit has been reached will cause an older token to be revoked.

  12. Can I use (session=0) single-use AuthSub tokens?

    No. You must always use session=1 to request a session token from AuthSub.

  13. Is there a programmatic (non browser-based) way to get an AuthSub token?

    Yes. ClientLogin is available for installed applications. AuthSub should be used for all web applications to guarantee users consciously review terms and grant permissions to linked applications.

Back to top

Managing Private keys and certificates

  1. How do I register my next URL?

    You can use the "Manage Domains" tool at https://www.google.com/accounts/ManageDomains. For additional information, refer to the Registration for Web-Based Applications documentation.

  2. How do I upload a X.509 certificate (in PEM format)?

    1. Login to the Manage Domains tool with the Google Account you've used for registering your PRODUCTION Next URL
    2. Click Manage www.yourproductionurl.com
    3. Upload an X.509 certificate in PEM format where it says "Upload new X.509 cert"

  3. What type and format of keys and certificates are supported to communicate with Google Health securely using registered mode?

    To communicate with Google Health securely via registered mode, you will need to generate a set of RSA keys and a corresponding X.509 certificate (in PEM format). For more information on this, see the Generating keys and certificates for use with registered mode section of AuthSub documentation.

  4. May I use any of my registered certificates during the process of upgrading my AuthSub token and creating my GoogleService?

    Yes, but each AuthSub token is bound to the certificate that was used when upgrading it to a session token. So future calls when using that token via the GoogleService instance must use that certificate when communicating.

  5. What options do I choose when using windows export wizard to export my certificate information before sending to authsub?

    Choose "No, do not export the private key" and "Base-64 encoded X.509 (.CER)" as the output format.

  6. I have imported my certificate into my .NET certificate store and cannot get it back out. What should I do?

    Your IIS instance may not have read privileges to your certificate store. When you use cacls.exe add these switches to the command: e.g. "<iisaccount>".

Back to top

Posting and Reading Profile Data

  1. Can a linked application service update a profile programmatically?

    Yes. By design, whenever a linked application service submits a new notice, it will be automatically reconciled into the associated profile.

  2. How can I tell how Google Health parsed and coded a posting?

    The result of all API calls that insert data is an Atom entry which has the document as it was parsed and processed on the server. In this result Entry you will find the server time stamp, the entry's id, and any coding applied.

  3. What are Atom feeds and how are they used by Google Health?

    Similar to RSS, the Atom Syndication Format (Atom feeds) is an XML language used for syndicating feeds over HTTP. Google Health uses Atom feeds when exchanging CCR data with linked applications.

  4. Do I have to digitally sign requests if I created my AuthSub token with a private key?

    Yes, if the AuthSub token is generated using a private key then any use of that token will always require using the private key as well. Otherwise, all attempts to publish notices or read profiles without the key will receive a 401 error.

Back to top

Data Format

  1. What is the difference between CCR and Google Health's subset of CCR?

    The CCR (Continuity of Care Record) standard is an XML format defined by the medical industry under the auspices of ASTM International to transport summary personal health data (www.ccrstandard.com). Refer to the Google Health and CCR document for a more in-depth explanation of this subset of CCR.

  2. Are my documents saved in CCR or Google Health's subset of CCR format?

    Feeds accept CCR documents and Google Health's subset of CCR as input, and they will be stored as originals. However upon retrieval, the feeds will contain documents in Google Health's subset of CCR. The response from a POST operation will indicate any data transformation that was performed.

  3. Is there a size limit to the CCR posts?

    Incoming CCR posts are limited to a maximum size of 1MB. However, there are no constraints on the number of nodes.

  4. Which medical coding systems can I use for each category (e.g. Allergies, Medications) in a Google Health's subset of CCR?

    There are many different coding systems in use by the medical community. The Google Health and CCR document provides a description of the coding systems Google Health recognizes for each category.

Back to top

Miscellaneous

  1. Is it possible to use an HTTP proxy with the Google Health API?

    Currently, you will have to manually change the AuthSubUtils class (in Java) in order to use a proxy.

  2. I need to provide a 'next url' for authsub. How to I do this?

    When developing locally, you may use 'localhost' (any protocol and any port) as the next url. You will eventually need to register some urls with AuthSub. Your company should determine all network-local urls and register those through an Google Health support provider. Next, your company should determine all internet facing computers that will be registering users via AuthSub and follow the instructions here for registration of those. You may also edit your "hosts" (or equivalent) file to forward calls from a registered next url to your local machine to help with testing.

Back to top

Troubleshooting

  1. Do you have any tips or short sample code for common issues?

    You should browse the Google Data API Tips Blog for help with both our client libraries and making raw requests. The Client Libraries and Sample Code page also lists some additional resources.

  2. Items I added to my profile are labeled "not in guide". How do I get these items to map so that Google Health recognizes them?

    See the Google Health and CCR document. This specification contains information on how to properly form CCR data so that it maps into Google Health as expected.

  3. My question is not answered here. Where can I send my question?

    Visit the Google Health Developers discussion forum.

Back to top