Heartbridge: A command-line tool to transfer iOS Health heart rate data to your computer

mmascioni profile image Matthew Mascioni ・2 min read

My Final Project: Heartbridge

This was a small project I put together this year (final year of engineering woo!) I wanted an easy way to transfer heart rate readings from my iPhone/Apple Watch to my Mac so I could play around with the data using something like pandas or visualize it differently. This command-line tool is the result! It can export data as a CSV or JSON file depending on what arguments get passed in.

Using the tool to receive heart rate data from my iPhone

Link to Code

GitHub logo mm / heartbridge

Using the iOS Shortcuts app and Python together to export heart rate data stored in the Health app to a JSON/CSV file.

Heartbridge: iOS Heart Rate Data Export

Build Status

Combined with an Apple Watch, the iOS Health app contains a wealth of heart rate readings. I always found these readings a little difficult to play with in the Health app, and couldn't find a way to easily export them to a format I could manipulate/visualize the readings using (like a JSON or CSV file).

Fortunately with the Shortcuts app, accessing this data is a lot easier. This combines a shortcut with a quick HTTP endpoint to transfer heart rate data from your iOS device to your Mac or PC. It was a fun little experiment for me to see how these two could work together. It has no dependencies besides what's already included in the Python standard library.

Heartbridge is a command-line program that can receive data from Shortcuts (via HTTP), automatically export it to the directory of your choosing (in CSV or…

How I built it/how it works

This was built in Python (as of now it only depends on what comes with the Python standard library), and makes use of an iOS shortcut (using the native Shortcuts app) I wrote as well. The Python package, when run will start accepting HTTP requests at a specified port (defaults to 8888).

When the shortcut is run on the user's iPhone, they'll be asked to select a date range of heart rate data they want to export. Readings will be sent in the body of an HTTP POST request to that same port on their computer, provided they're on the same network. The JSON in the request body is processed further by Heartbridge once it is received, and the readings are exported to either a CSV or JSON file for further exploration.

This project was a great way to learn about using a continuous integration tool for unit testing (to make sure my unit tests pass with every commit I make). For this I used Travis CI to hook into my GitHub repo and run code in my commits against the unit tests I had written. This was offered as part of the GitHub Student Developer Pack and I loved using it!

This was also my first time submitting my code as a package on PyPI, which allows anyone with pip to install it at the command line and run it easily. This required me to structure my code as an overall package, which I've always wanted to learn and finally got a chance to with this project. I'm excited to create more of them in the future!

Posted on by:

mmascioni profile

Matthew Mascioni


Recent engineering grad interested in web dev, product and data. Writing about stuff I learn or build along the way!


markdown guide