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

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.

Link to Code

mm / heartbridge

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

Heartbridge: iOS Health Data Export

Heartbridge is a command-line tool that exports health data from your iOS device to your local computer, with the help of an iOS Shortcut. It supports exporting many types of data from the Health app, including:

• Heart Rate
• Resting Heart Rate
• Heart Rate Variability
• Steps
• Flights Climbed
• Cycling Distance

Heartbridge receives data from the Shortcuts app (via HTTP), automatically exports it to the directory of your choosing (in CSV or JSON format) and automatically names files according to the health data type and date range they cover. Exported files contain a time stamp ("Start Date" in Health) and reading ("Value" in Health). To read more about how the file exports look depending on the data type, check out Data Type Support.

If you don't want to use the built-in CLI or server, you can also use Heartbridge to parse data from Shortcuts directly-- for…

View on GitHub

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!