Python SMART on FHIR client
Clone or download
Failed to load latest commit information.
fhir-parser @ 6eb44a9 Update to FHIR v3.0.0.11832 Mar 22, 2017
fhir-parser-resources Fix relative reference resolution within bundles (#53) Jul 21, 2018
fhirclient Fix relative reference resolution within bundles (#53) Jul 21, 2018
.bumpversion.cfg Increment version to 3.2.0 Feb 6, 2018
.gitignore Merge branch 'develop' into feature/latest-ci Nov 17, 2016
.gitmodules It helps to actually add `fair-parser` as a submodule Sep 16, 2014 Fix refresh_token parsing, use named logger Feb 27, 2017 Convert AUTHORS and CONTRIBUTING to Markdown and add to docs Oct 31, 2014
Doxyfile Increment version to 3.2.0 Feb 6, 2018
Doxyfilter Setup for Doxygen docs generation Oct 31, 2014
Doxystyle.css Setup for Doxygen docs generation Oct 31, 2014
LICENSE update license Apr 21, 2015 Add MANIFEST file Nov 6, 2014 Fix in README (#42) Nov 1, 2017 Sample app now able to handle referenced medications and filter codings Feb 8, 2018 changed tabs to 4 spaces to be pep8 compliant. Jan 6, 2016 Update fhir-parser and migrate Feb 14, 2017
requirements.txt Enable server to make signed requests Sep 23, 2014
requirements_flask_app.txt Update requirements_flask_app.txt Feb 13, 2018
setup.cfg Initial commit Aug 27, 2014 Bump version numbers Mar 22, 2017 Regenerate models with new inheritance graph Feb 24, 2016
tox.ini Bump version numbers Mar 22, 2017


This is fhirclient, a flexible Python client for FHIR servers supporting the SMART on FHIR protocol. The client is compatible with Python 2.7.10 and Python 3.

Client versioning is not identical to FHIR versioning. The master branch is usually on the latest version of the client as shown below, possibly on bugfix releases thereof. The develop branch should be on recent freezes, and the feature/latest-ci branch is periodically updated to the latest FHIR continuous integration builds.

Version FHIR  
3.0.0 3.0.0 (STU-3)
x.x 1.8.0 (STU-3 Ballot, Jan 2017)
x.x 1.6.0 (STU-3 Ballot, Sep 2016)
1.0.3 1.0.2 (DSTU 2)
1.0 1.0.1 (DSTU 2)
0.5 (DSTU 2 Ballot, May 2015)
0.0.4 (DSTU 1)
0.0.3 (DSTU 1)
0.0.2 (DSTU 1)


pip install fhirclient


Technical documentation is available at

Client Use

To connect to a SMART on FHIR server (or any open FHIR server), you can use the FHIRClient class. It will initialize and handle a FHIRServer instance, your actual handle to the FHIR server you'd like to access.

Read Data from Server

To read a given patient from an open FHIR server, you can use:

from fhirclient import client
settings = {
    'app_id': 'my_web_app',
    'api_base': ''
smart = client.FHIRClient(settings=settings)

import fhirclient.models.patient as p
patient ='hca-pat-1', smart.server)
# '1963-06-12'
# 'Christy Ebert'

If this is a protected server, you will first have to send your user to the authorize endpoint to log in. Just call smart.authorize_url to obtain the correct URL. You can use smart.prepare(), which will return False if the server is protected and you need to authorize. The smart.ready property has the same purpose, it will however not retrieve the server's CapabilityStatement resource and hence is only useful as a quick check whether the server instance is ready.

smart = client.FHIRClient(settings=settings)
# prints `False`
# prints `True` after fetching CapabilityStatement
# prints `True`
# prints `True` immediately
# is `None`

You can work with the FHIRServer class directly, without using FHIRClient, but this is not recommended:

smart = server.FHIRServer(None, '')
import fhirclient.models.patient as p
patient ='hca-pat-1', smart)[0].given
# ['Christy']
Search Records on Server

You can also search for resources matching a particular set of criteria:

smart = client.FHIRClient(settings=settings)
import fhirclient.models.procedure as p
search = p.Procedure.where(struct={'subject': 'hca-pat-1', 'status': 'completed'})
procedures = search.perform_resources(smart.server)
for procedure in procedures:
    # {'status': u'completed', 'code': {'text': u'Lumpectomy w/ SN', ...

# to get the raw Bundle instead of resources only, you can use:
bundle = search.perform(smart.server)

Data Model Use

The client contains data model classes, built using fhir-parser, that handle (de)serialization and allow to work with FHIR data in a Pythonic way. Starting with version 1.0.5, data model validity are enforced to a certain degree.

Initialize Data Model

import fhirclient.models.patient as p
import fhirclient.models.humanname as hn
patient = p.Patient({'id': 'patient-1'})
# prints `patient-1`

name = hn.HumanName()
name.given = ['Peter'] = 'Parker' = [name]
# prints patient's JSON representation, now with id and name

name.given = 'Peter'
# throws FHIRValidationError:
# {root}:
#   name:
#     given:
#       Expecting property "given" on <class 'fhirclient.models.humanname.HumanName'> to be list, but is <class 'str'>

Initialize from JSON file

import json
import fhirclient.models.patient as p
with open('path/to/patient.json', 'r') as h:
    pjs = json.load(h)
patient = p.Patient(pjs)[0].given
# prints patient's given name array in the first `name` property

Flask App

Take a look at to see how you can use the client in a simple (Flask) app. This app starts a webserver, listening on localhost:8000, and prompts you to login to our sandbox server and select a patient. It then goes on to retrieve the selected patient's demographics and med prescriptions and lists them in a simple HTML page.

The Flask demo app has separate requirements. Clone the client-py repository, then best create a virtual environment and install the needed packages like so:

git clone
cd client-py
virtualenv -p python3 env
. env/bin/activate
pip install -r requirements_flask_app.txt

Building Distribution

pip install -r requirements.txt
python sdist
python bdist_wheel

Incrementing the lib version

bumpversion patch
bumpversion minor
bumpversion major

Docs Generation

Docs are generated with Doxygen and doxypypy. You can install doxypypy via pip: pip install doxypypy. Then you can just run Doxygen, configuration is stored in the Doxyfile.

Running Doxygen will put the generated documentation into docs, the HTML files into docs/html. Those files make up the content of the gh-pages branch. I usually perform a second checkout of the gh-pages branch and copy the html files over, with:

rsync -a docs/html/ ../client-py-web/

PyPi Publishing (notes for SMART team)

Using setuptools (Note: Alternatively, you can use twine

Make sure that you have the PyPi account credentials in your account

copy to ~/.pypirc

Test the build

python sdist
python bdist_wheel

Upload the packages to PyPi

python sdist upload -r pypi
python bdist_wheel upload -r pypi