Package: cms-bluebutton-sdk
Python SDK for Blue Button 2.0 APIThis Python software development kit (SDK) provides tools and resources for developers integrating with theCMS Blue Button 2.0 (BB2.0) API.Table of ContentsPrerequisitesInstallationConfiguration ParametersConfiguration MethodsUsageSample AppAboutLicenseSecurityHelp and SupportPrerequisitesYou'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, seeTry the API.Installationpipinstallcms-bluebutton-sdkConfiguration ParametersRequired SDK configuration parameters include:ParameterValueDefaultDescriptionenvironmentSANDBOXorPRODUCTIONSANDBOXBlue Button 2.0 API environmentversion1or22Blue Button 2.0 versionclient_idyour_client_idOAuth2.0 client ID of your appclient_secretyour_client_secretOAuth2.0 client secret of your appcallback_urlhttps://www.example.com/callbackOAuth2.0 callback URL of your appAccess Token Refresh on ExpireSDK 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, settoken_refresh_on_expiretofalse.FHIR Requests Retry SettingsRetry is enabled by default for FHIR requests. The folllowing parameters are available for the exponential back off retry algorithm.Retry parameterValue (default)Descriptionbackoff_factor5Backoff factor in secondstotal3Max retriesstatus_forcelist[500,502,503,504]Error response codes to retry onThe exponential backoff factor (in seconds) is used to calculate interval between retries using the formulabackoff_factor * (2 ** (i - 1))whereistarts from 0.Example:Abackoff_factorof 5 seconds generates the wait intervals: 2.5, 5, 10, ...To disable the retry, settotal = 0Environments and DataThe Blue Button 2.0 API is available in V1 and V2 in a sandbox and production environment.Sandbox location:https://sandbox.bluebutton.cms.govProduction location:https://api.bluebutton.cms.govVersion data formats:V1: FHIR STU3V2: FHIR R4Sample 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 MethodsThere are three ways to configure the SDK when instantiating aBlueButtonclass 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 DataBelow are code snippets showing the SDK used with Python server and Flask.fromflaskimportFlaskfromflaskimportredirect,requestfromcms_bluebuttonimportBlueButton,AuthorizationToken# initialize the appapp=Flask(__name__)# Instantiate SDK class instance via conf in filebb=BlueButton()# auth_data is saved for the current userauth_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"])defget_auth_url():returnbb.generate_authorize_url(auth_data)@app.route('/api/bluebutton/callback/',methods=['GET'])defauthorization_callback():request_query=request.argscode=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 grantaccess to their demographic data and claims data or only claims data.Check the scopeof the current access token as shown below:"""scopes=auth_token.scope# iterate scope entries here or check if a permission is in the scopeif"patient/Patient.read"inscopes:# 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, profiletry: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()exceptExceptionasex:print(ex)returnresultif__name__=='__main__':app.run(debug=True,host='0.0.0.0',port=3001)Sample AppFor a complete Python React sample app, seeCMS Blue Button Python Sample App.About the Blue Button 2.0 APITheBlue Button 2.0 APIprovides Medicare enrollee claims data to applications using theOAuth2.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.LicenseThe CMS Blue Button 2.0 Python SDK is licensed under the Creative Commons Zero v1.0 Universal. For more details, seeLicense.SecurityWe 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 theCMS Vulnerability Disclosure Policyand follow the directions for reporting.Help and SupportGot questions? Need help troubleshooting? Want to propose a new feature? Contact the Blue Button 2.0 team and connect with the community in ourGoogle Group.