Skip to main content

Python SDK for Blue Button 2.0 API

This Python software development kit (SDK) provides tools and resources for developers integrating with the CMS Blue Button 2.0 (BB2.0) API.

Table of Contents

Prerequisites

You'll need a sandbox account and sample access token to access data from the Blue Button 2.0 API.

To learn how to create a sandbox account and generate a sample access token, see Try the API.

Installation

pip install cms-bluebutton-sdk

Configuration Parameters

Required SDK configuration parameters include:

Parameter Value Default Description
environment SANDBOX or PRODUCTION SANDBOX Blue Button 2.0 API environment
version 1 or 2 2 Blue Button 2.0 version
client_id your_client_id OAuth2.0 client ID of your app
client_secret your_client_secret OAuth2.0 client secret of your app
callback_url https://www.example.com/callback OAuth2.0 callback URL of your app

Access Token Refresh on Expire

SDK FHIR requests check whether the access token is expired before the data endpoint call. By default, an expired token will refresh. To disable token refresh, set token_refresh_on_expire to false.

FHIR Requests Retry Settings

Retry is enabled by default for FHIR requests. The folllowing parameters are available for the exponential back off retry algorithm.

Retry parameter Value (default) Description
backoff_factor 5 Backoff factor in seconds
total 3 Max retries
status_forcelist [500, 502, 503, 504] Error response codes to retry on

The exponential backoff factor (in seconds) is used to calculate interval between retries using the formula backoff_factor * (2 ** (i - 1)) where i starts from 0.

Example:

A backoff_factor of 5 seconds generates the wait intervals: 2.5, 5, 10, ...

To disable the retry, set total = 0

Environments and Data

The Blue Button 2.0 API is available in V1 and V2 in a sandbox and production environment.

Version data formats:

  • V1: FHIR STU3
  • V2: FHIR R4

Sample configuration JSON with default version and environment:

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "callback_url": "https://www.example.com/",
}

If needed, you can set your application's target environment and API version.

Example:

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "callback_url": "https://www.example.com/",
  "version": "2",
  "environment": "PRODUCTION"
}

Configuration Methods

There are three ways to configure the SDK when instantiating a BlueButton class instance.

Python Dictionary

- A dictionary of configuration key:value pairs can be used.
- Configuration values can be provided from your own application's configuration method.
- Example code:
  ```python
  bb = BlueButton({
           "environment": "PRODUCTION",
           "client_id": "your_client_id",
           "client_secret": "your_client_secret",
           "callback_url": "https://www.example.com/callback",
           "version": 2,
           "retry_settings": {
               "total": 3,
               "backoff_factor": 5,
               "status_forcelist": [500, 502, 503, 504]
           }
        }
  ```

JSON config file

- This is using a configuration file that is in a JSON format.
- This is stored in a local file.
- The default location is in the current working directory with a file name: .bluebutton-config.json
- Example code:
  ```python
  bb = BlueButton("settings/my_bb2_sdk_conf.json")
  ```
- Example JSON in file:
  ```json
  {
      "environment": "SANDBOX",
      "client_id": "your_client_id",
      "client_secret": "your_client_secret",
      "callback_url": "https://www.example.com/callback",
      "version": 2,
      "retry_settings": {
          "total": 3,
          "backoff_factor": 5,
          "status_forcelist": [500, 502, 503, 504]
      }
  }
  ```

YAML config file

- This is using a configuration file that is in a YAML format.
- This is stored in a local file.
- The default location is in the current working directory with a file name: .bluebutton-config.yaml
- Example code:
  ```python
  bb = BlueButton("settings/my_bb2_sdk_conf.yaml")
  ```
- Example YAML in file:
  ```yaml
  environment: "SANDBOX"
  client_id: "id"
  client_secret: "your_client_secret"
  callback_url: "https://www.example.com/callback"
  version: 2
  ```

Sample Usage: Obtain Access Grant, Probe Scope, and Access Data

Below are code snippets showing the SDK used with Python server and Flask.

from flask import Flask
from flask import redirect, request
from cms_bluebutton import BlueButton, AuthorizationToken

# initialize the app
app = Flask(__name__)

# Instantiate SDK class instance via conf in file
bb = BlueButton()

# auth_data is saved for the current user
auth_data = bb.generate_auth_data()

"""
AuthorizationToken holds access grant info:
  access token, expire in, expire at, token type, scope, refreh token, etc.
It is associated with current logged in user in real app.
Check SDK python docs for more details.
"""

auth_token = None

# Start authorize flow: Response with URL to redirect to Medicare.gov beneficiary login
@app.route("/", methods=["GET"])
def get_auth_url():
    return bb.generate_authorize_url(auth_data)


@app.route('/api/bluebutton/callback/', methods=['GET'])
def authorization_callback():
    request_query = request.args
    code = request_query.get('code')
    state = request_query.get('state')

    auth_token = bb.get_authorization_token(auth_data, code, state)

    """
    Now access token obtained.

    Note: During authorization, the beneficiary can grant
    access to their demographic data and claims data or only claims data.

    Check the scope
    of the current access token as shown below:
    """
    scopes = auth_token.scope

    # iterate scope entries here or check if a permission is in the scope
    if "patient/Patient.read" in scopes: 
        # patient info access granted

    """
    1. access token scope where demographic info included:
    
    scope: [
       "patient/Coverage.read",
       "patient/ExplanationOfBenefit.read",
       "patient/Patient.read",
       "profile",
    ]
    
    2. access token scope where demagraphic info not included:
    
    scope: [
        "patient/Coverage.read",
        "patient/ExplanationOfBenefit.read",
    ]
    """
    config = {
        "auth_token": auth_token,
        "params": {},
        "url": "to be overriden"
    }

    result = {}

    # fetch eob, patient, coverage, profile
    try:
        eob_data = bb.get_explaination_of_benefit_data(config)
        result['eob_data'] = eob_data['response'].json()
        eob_data = eob_data['response'].json()
        result['eob_data'] = eob_data

        # A FHIR search response can result in a large number of resources. 
        # For example, an EOB search of a beneficiary could return hundreds 
        # of resources. By default, search results are grouped into
        # pages with 10 resources each. For example, 
        # bb.get_explaination_of_benefit_data(config) returns the
        # first page of resources as a FHIR bundle with a link section 
        # of page navigation URLs. Pagination link names include 
        # 'first,' 'last,' 'self,' next,' and 'previous.' 
        # To get all the pages, use bb.get_pages(data, config).
        
        eob_pages = bb.get_pages(eob_data, config)
        result['eob_pages'] = eob_pages['pages']
        auth_token = eob_pages['auth_token']

        pt_data = bb.get_patient_data(config)
        result['patient_data'] = pt_data['response'].json()

        coverage_data = bb.get_coverage_data(config)
        result['coverage_data'] = coverage_data['response'].json()

        profile_data = bb.get_profile_data(config)
        result['profile_data'] = profile_data['response'].json()
    except Exception as ex:
        print(ex)

    return result


if __name__ == '__main__':
    app.run(debug=True, host='0.0.0.0', port=3001)

Sample App

For a complete Python React sample app, see CMS Blue Button Python Sample App.

About the Blue Button 2.0 API

The Blue Button 2.0 API provides Medicare enrollee claims data to applications using the OAuth2.0 authorization flow. We aim to provide a developer-friendly, standards-based API that enables people with Medicare to connect their claims data to the applications, services, and research programs they trust.

License

The CMS Blue Button 2.0 Python SDK is licensed under the Creative Commons Zero v1.0 Universal. For more details, see License.

Security

We do our best to keep our SDKs up to date with vulnerability patching and security testing, but you are responsible for your own review and testing before implementation.

To report vulnerabilities, please see the CMS Vulnerability Disclosure Policy and follow the directions for reporting.

Help and Support

Got questions? Need help troubleshooting? Want to propose a new feature? Contact the Blue Button 2.0 team and connect with the community in our Google Group.

Metadata

Release files for cms-bluebutton-sdk 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for cms-bluebutton-sdk 1.0.1
File Interpreter ABI Platform Actions
cms_bluebutton_sdk-1.0.1-py3-none-any.whl Python 3 none any Details for cms_bluebutton_sdk-1.0.1-py3-none-any.whl

Release files / cms_bluebutton_sdk-1.0.1-py3-none-any.whl

Download URL cms_bluebutton_sdk-1.0.1-py3-none-any.whl
Size 17.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ca10df618496a08bacf363da856a9d9e7df7b0b25d7823f3837f015721c7564b
BLAKE2b-256 checksum
How to use checksums
28a2342499cebd7423338dbe82eb610781ca4ab6274681dfe17359352fa2be8a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.2 CPython/3.10.7

Security for cms-bluebutton-sdk 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page