Package: heartbridge
Heartbridge: iOS Health Data ExportHeartbridge 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 RateResting Heart RateHeart Rate VariabilityStepsFlights ClimbedCycling DistanceHeartbridge receives data from theShortcutsapp (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 outData 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 example, if you wanted to automatically push data to a database on your own server.Note: The CLI is designed to be run on your local computer! It's not production ready; only run if you trust the devices on your local network.Getting StartedYou will need:A computer with Python (>=3.8) installedAn iPhone withShortcutsinstalled, on the same networkInstall heartbridge usingpipat a command line (or use the distribution packages underreleases):pipinstallheartbridgeAfterwards, runheartbridgeat your command line:heartbridgeThis will save all exported files to the current working directory in CSV format. You can override both of these things with the--directoryand--typearguments. If I wanted JSON files on my desktop instead, I could go with:heartbridge--directory~/Desktop--typejsonYou can also change the port heartbridge will listen for data on (by default 8888) by passing an argument toport. For a full list of arguments you can pass, typeheartbridge --help.Make note of the endpoint URL the script prints out, and ensure the script is allowed to accept incoming connections if your firewall prompts you. In this case, mine would behttp://matt-mac.local:8888:➜~heartbridge
⚡Waitingtoreceivehealthdataathttp://matt-mac.local:8888...(PressCtrl+Ctostop)On your iPhone,download the shortcut to extract Health samples. It will ask you what the HTTP endpoint URL you just noted is.Open up the Shortcut. In the first step, you can change "Type" to be whatever data you're trying to export (Heart Rate is selected by default).Run the shortcut! You will be prompted to select the date range you want to cover. The end date of the date range you specify is not included in the data returned. For example, to get all data for May 2nd, 2020:The script will output information about the data it receives from the shortcut to the console:➜~heartbridge
⚡Waitingtoreceivehealthdataathttp://matt-mac.local:8888...(PressCtrl+Ctostop)💛DetectedHeartRatedatawith8429samples.
✅Successfullyexporteddatato/Users/mattmascioni/heart-rate-Apr01-2021-Apr16-2021.csvThe program will continue to run and listen for new data until stopped. Stop running the server (Ctrl-C) whenever you're finished exporting all the data you need. Enjoy exploring your health data!All Command Line OptionsUsage:heartbridge[OPTIONS]OpensatemporaryHTTPendpointtosendhealthdatafromShortcutstoyourcomputer.

Options:--directoryDIRECTORYSettheoutputdirectoryforexportedfiles.Defaultstocurrentdirectory.Willcreatedirectoryifitdoesnnotalreadyexist.--type[csv|json]Settheoutputfiletype.Canbecsvorjson.Defaultstocsv.--portINTEGERRANGESettheporttolistenforHTTPrequestson.Defaultsto8888.Using Heartbridge without the CLITypingheartbridgein a shell opens up a temporary server to send data from the shortcut to your computer. If you don't want this behaviour (for example, if you already have a server that can accept the JSON data Shortcuts sends), you can use Heartbridge's Shortcuts data parsing tools directly, which are contained in theHealthclass. Say your endpoint stores the incoming request JSON in theincoming_shortcuts_jsondict, you could then do things with the readings using:>>>fromheartbridgeimportHealth>>>health=Health()>>>health.load_from_shortcuts(data=incoming_shortcuts_json)>>>health.reading_type_slug'heart-rate'>>>first_reading=health.readings[0]>>>first_reading.timestampdatetime.datetime(2021,4,17,14,16,31,780731)>>>first_reading.get_value()40>>>first_reading.to_dict(){'timestamp':'2021-04-17 14:16:31','heart_rate':40}health.readingsis a list ofBaseHealthReading-subclassed data objects. Depending on the health data passed in, the class may be one of:Heart Rate:HeartRateReadingResting Heart Rate:RestingHeartRateReadingHeart Rate Variability:HeartRateVariabilityReadingSteps:StepsReadingFlights Climbed:FlightsClimbedReadingCycling Distance:CyclingDistanceReadingAll others:GenericHealthReadingNo matter what the class is, you can always access therecord.get_value()andrecord.to_dict()methods to get the health sample value/dictionary representation respectively, and.timestampproperty to get the health "Start Date" of the reading as a datetime.NotesData Type SupportHeartbridge supports pretty much any Health record exported by Shortcuts. For some health records, there's built in support for adding relevant headers/keys in the resulting CSV/JSON file:Data TypeStart Date Header/KeyValue Header/KeyHeart Ratetimestampheart_rateResting Heart Ratetimestampresting_heart_rateHeart Rate Variabilitytimestampheart_rate_variabilityStepstimestampstep_countFlights ClimbedtimestampclimbedCycling Distancetimestampdistance_cycledAll other recordstimestampreadingFor example, if Steps data was sent, the resulting CSV file would havetimestamp, step_countheaders.Motivation for this projectCombined with an Apple Watch, the iOS Health app contains a wealth of heart rate and other health 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 theShortcutsapp, 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. The original version of Heartbridge was for heart rate data only, but now it can work with more sample types!Shortcuts data formatThe shortcut uses the "Find All Health Samples where" action:This returns a result set of health samples including the start date of the reading, the value and the duration the reading was taken for. What I found difficult was exporting multiple attributes of this set's data at once -- I was only able to export the date into one array (an array of dates) and the actual heart rate value into one array (an array of values). Once these are tied into a dictionary, the resulting JSON the shortcut produces looks something like this:{"type":"Heart Rate","dates":["2019-12-16 08:24:36","2019-12-16 08:26:39",...],"values":["74","72",...]}Both thedatesandvalueslist is ordered in ascending order by start date. Doing it this way allowed me to avoid using a "Repeat with Each..." action on the health sample set which introduced a lot of slowness to the shortcut.Among other things, the Python script is used to combine those two arrays into a list of tuples. The above JSON would be transformed into[("2019-12-16 08:24:36", 74), ("2019-12-16 08:26:39", 72)]by the script, once it's received in an HTTP POST request. It's then converted to a CSV or JSON file.