My favorites | English | Sign in

Google Health Data API

Developer Best Practices

User Interface / Flow

  1. Be explicitly clear to users what they are signing up for:
    • A one-time, upfront authorization to transfer information securely.
    • Ongoing updates will happen behind the scenes. It's important to make this clear to users - otherwise they may think they need to explicitly initiate every data transfer.
    • They can revoke this authorization at anytime, either from the 3rd party app, or from their Google Health account.
  2. Keep the number of registration steps and screens to a minimum
  3. After clicking "Link to Profile" from within Google Health, your service should:
    • Make clear to the user that they are part of a stepwise flow.
    • Take the user directly to a page on your site where he/she can transfer data to/from Google Health. If they must first login, put wording such as "In order to link to your Google Health profile, please login to your YOURMEDSERVICE.COM
  4. Google Health connection settings - in your services' web interface
    • Have a section on your site (Profile, or Settings page), where the user can manage their Google Health connection
    • This is where the user can:
      • Check their link (token) status
      • See any expiration date of the link/token (if you are setting your own expiration dates)
      • Unlink their account from their Google Health profile

Token Management

  1. Once a user's profile has been linked, there's no need to go through the approval process again. However, if you query a feed with an invalid token (the user unlinks your application from within Google Health), and error will occur. In this case, your application should recover and initiate the approval process.
  2. When the user revokes a token in your application or in Google Health, delete the stored session token from your database.
  3. Only allow one active token per user.
  4. The maximum number of active tokens per Google Health profile, per domain is 5.

Data Updates

  1. API requests are always initiated by the application, never by Google
  2. Applications should only need to get permission ("Link this profile" page) from the user to use his/her once. Subsequent requests and ongoing updates should reference the long-lived AuthSub/OAuth token.
  3. Applications should log in their system when they last posted data to Google
  4. Applications should log responses from Google
  5. Requests must be signed for /health requests
  6. When to update data:
    • Based on data changes: your backend has some relevant data updated which triggers a push to Google
    • Based on user action: the user clicks a "send updates to Google" button in your site's portal
    • Based on time: nightly, daily, hourly, etc.
  7. Data to send:
    • First time after AuthSub/OAuth approval:
      • Send full data set. Usability tests have shown that users expect the data to show up in their profile immediately. If they don't see data in their Google Health account right away, they may conclude that your application is broken and/or not worth using.
      • After a user clicks "Yes, link my accounts" on the AuthSub approval page, Google passes a single-use token to the application. This token should be upgraded immediately to a long-lived session token and stored in your database.
      • Once you have a session token, send data to Google Health. If this takes >5 seconds to send, we recommend posting an animated "Sending Data to Google" message... before the redirect back to Google Health.
    • Ongoing:
      • Log data pushes to Google
      • Only send new information since the last post. If nothing has changed, there's no need to send data to Google

    8. Data Content

    1. All data should be sent in coded format. Don't include things like medication dosage and frequency as part of the NAME field; these should be in the appropriate CCR fields.
    2. To provide the best user experience, send a CCR message with "# of Refills" decremented by 1 as consumers request and pickup refills.

    A Note on CCR

    CCR allows multiple codes from different coding systems to accompany an object. Google Health will interpret the following codes:

    1. Medications: RxNorm, NDC, FDB
    2. Conditions and symptoms: SNOMEDCT, ICD9, FDB
    3. Procedures: CPT, SNOMEDCT
    4. Allergies: SNOMEDCT
    5. Immunizations: CPT
    6. Lab test: LOINC, CPT, SNOMED

    Service Action Links

    1. These are the links that will show on the users home page in Google Health AFTER they have connected their health profile with your service.
    2. Action Link descriptions must be CALL TO ACTIONS, such as "Get a second opinion".

    Suggestions

    1. When a new profile link is set up, your organzation should notify customer (via e-mail or other form) that they setup a link with Google Health.
    2. Allow users to download all of their data in some structured format (CSV, CCR, etc.)

    Back to top