https://github.com/stanfordbdhg/healthkitonfhir
Converts HealthKit data to HL7 FHIR resources
https://github.com/stanfordbdhg/healthkitonfhir
fhir healthkit stanford swift
Last synced: 4 months ago
JSON representation
Converts HealthKit data to HL7 FHIR resources
- Host: GitHub
- URL: https://github.com/stanfordbdhg/healthkitonfhir
- Owner: StanfordBDHG
- License: mit
- Created: 2022-11-23T18:19:55.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-07-03T13:17:23.000Z (5 months ago)
- Last Synced: 2025-07-03T14:30:26.555Z (5 months ago)
- Topics: fhir, healthkit, stanford, swift
- Language: Swift
- Homepage: https://swiftpackageindex.com/StanfordBDHG/HealthKitOnFHIR/documentation
- Size: 224 KB
- Stars: 24
- Watchers: 14
- Forks: 8
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
- Citation: CITATION.cff
Awesome Lists containing this project
README
# HealthKitOnFHIR
[](https://github.com/StanfordBDHG/HealthKitOnFHIR/actions/workflows/build-and-test.yml)
[](https://codecov.io/gh/StanfordBDHG/HealthKitOnFHIR)
[](https://zenodo.org/badge/latestdoi/569837859)
[](https://swiftpackageindex.com/StanfordBDHG/HealthKitOnFHIR)
[](https://swiftpackageindex.com/StanfordBDHG/HealthKitOnFHIR)
The HealthKitOnFHIR library provides extensions that convert supported HealthKit samples to corresponding FHIR resources using [FHIRModels](https://github.com/apple/FHIRModels) encapsulated in a [ResourceProxy](https://github.com/apple/FHIRModels/blob/main/HowTo/Instantiation.md#1-use-resourceproxy).
For more information, please refer to the [API documentation](https://swiftpackageindex.com/StanfordBDHG/HealthKitOnFHIR/documentation).
HealthKitOnFHIR supports:
- Extensions to convert data from Apple HealthKit to HL7® FHIR® R4.
- Customizable mappings between HealthKit data types and standardized codes (e.g., LOINC)
Please refer to the [HKObject Support Table](Sources/HealthKitOnFHIR/HealthKitOnFHIR.docc/HKSampleSupportTables.md) for a complete list of supported types.
> [!NOTE]
> HealthKitOnFHIR will use the time zone specified in [HKMetadataKeyTimeZone](https://developer.apple.com/documentation/healthkit/hkmetadatakeytimezone) when creating FHIR Observations from HealthKit samples. If no time zone is specified, HealthKitOnFHIR will use the device's current time zone.
## Installation
HealthKitOnFHIR can be installed into your Xcode project using [Swift Package Manager](https://github.com/apple/swift-package-manager).
1. In Xcode 14 and newer (requires Swift 5.7), go to “File” » “Add Packages...”
2. Enter the URL to this GitHub repository, then select the `HealthKitOnFHIR` package to install.
## Usage
The HealthKitOnFHIR library provides extensions that convert supported HealthKit samples to corresponding FHIR resources using [FHIRModels](https://github.com/apple/FHIRModels) encapsulated in a [ResourceProxy](https://github.com/apple/FHIRModels/blob/main/HowTo/Instantiation.md#1-use-resourceproxy).
```swift
let sample: HKSample = // ...
let resource = try sample.resource()
```
### Observations
`HKQuantitySample`, `HKCategorySample`, `HKCorrelationSample`, `HKElectrocardiogram`, and `HKWorkout` will be converted into FHIR [Observation](https://hl7.org/fhir/R4/observation.html) resources encapsulated in a [ResourceProxy](https://github.com/apple/FHIRModels/blob/main/HowTo/Instantiation.md#1-use-resourceproxy).
```swift
let sample: HKQuantitySample = // ...
let observation = try sample.resource().get(if: Observation.self)
```
Codes and units can be customized by passing in a custom `HKSampleMapping` instance to the `resource(withMapping:)` method.
```swift
let sample: HKQuantitySample = // ...
let sampleMapping: HKSampleMapping = // ...
let observation = try sample.resource(withMapping: sampleMapping).get(if: Observation.self)
```
### Clinical Records
`HKClinicalRecord` will be converted to FHIR resources based on the type of its underlying data. Only records encoded in FHIR R4 are supported at this time.
```swift
let allergyRecord: HKClinicalRecord = // ...
let allergyIntolerance = try allergyRecord.resource().get(if: AllergyIntolerance.self)
```
## Example
In the following example, we will query the HealthKit store for heart rate data, convert the resulting samples to FHIR observations, and encode them into JSON.
```swift
import HealthKitOnFHIR
// Initialize an HKHealthStore instance and request permissions with it
// ...
let date = ISO8601DateFormatter().date(from: "1885-11-11T00:00:00-08:00") ?? .now
let sample = HKQuantitySample(
type: HKQuantityType(.heartRate),
quantity: HKQuantity(unit: HKUnit.count().unitDivided(by: .minute()), doubleValue: 42.0),
start: date,
end: date
)
// Convert the results to FHIR observations
let observation: Observation?
do {
try observation = sample.resource().get(if: Observation.self)
} catch {
// Handle any mapping errors here.
// ...
}
// Encode FHIR observations as JSON
let encoder = JSONEncoder()
encoder.outputFormatting = [.prettyPrinted, .withoutEscapingSlashes, .sortedKeys]
guard let observation,
let data = try? encoder.encode(observation) else {
// Handle any encoding errors here.
// ...
}
// Print the resulting JSON
let json = String(decoding: data, as: UTF8.self)
print(json)
```
The following example generates the following FHIR observation:
```json
{
"code" : {
"coding" : [
{
"code" : "8867-4",
"display" : "Heart rate",
"system" : "http://loinc.org"
}
]
},
"effectiveDateTime" : "1885-11-11T00:00:00-08:00",
"identifier" : [
{
"id" : "8BA093D9-B99B-4A3C-8C9E-98C86F49F5D8"
}
],
"issued" : "2023-01-01T00:00:00-08:00",
"resourceType" : "Observation",
"status" : "final",
"valueQuantity" : {
"code": "/min",
"unit": "beats/minute",
"system": "http://unitsofmeasure.org",
"value" : 42
}
}
```
## License
This project is licensed under the MIT License. See [Licenses](https://github.com/StanfordBDHG/HealthKitOnFHIR/tree/main/LICENSES) for more information.
## Contributors
This project is developed as part of the Stanford Biodesign for Digital Health projects at Stanford.
See [CONTRIBUTORS.md](https://github.com/StanfordBDHG/HealthKitOnFHIR/tree/main/CONTRIBUTORS.md) for a full list of all HealthKitOnFHIR contributors.
## Notices
HealthKit is a registered trademark of Apple, Inc.
FHIR is a registered trademark of Health Level Seven International.
