{"id":13493713,"url":"https://github.com/CoolCoderSJ/HCGateway","last_synced_at":"2025-03-28T12:32:20.616Z","repository":{"id":189705838,"uuid":"680683214","full_name":"CoolCoderSJ/HCGateway","owner":"CoolCoderSJ","description":"A universal REST API for apps like Google Fit, Fitbit, Samsung Health, and more utilizing the Android Health Connect API.","archived":false,"fork":false,"pushed_at":"2024-10-29T17:26:08.000Z","size":50239,"stargazers_count":100,"open_issues_count":2,"forks_count":20,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-29T18:49:25.333Z","etag":null,"topics":["android","fitbit","google-fit","healthconnect","rest-api","samsung-health"],"latest_commit_sha":null,"homepage":"https://hcgateway.shuchir.dev/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CoolCoderSJ.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-20T03:52:54.000Z","updated_at":"2024-10-28T23:41:41.000Z","dependencies_parsed_at":null,"dependency_job_id":"1affd1bd-00b0-4aac-9f39-b2d9539fb1c9","html_url":"https://github.com/CoolCoderSJ/HCGateway","commit_stats":null,"previous_names":["coolcodersj/hcgateway"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CoolCoderSJ%2FHCGateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CoolCoderSJ%2FHCGateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CoolCoderSJ%2FHCGateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CoolCoderSJ%2FHCGateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CoolCoderSJ","download_url":"https://codeload.github.com/CoolCoderSJ/HCGateway/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246030678,"owners_count":20712417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","fitbit","google-fit","healthconnect","rest-api","samsung-health"],"created_at":"2024-07-31T19:01:18.027Z","updated_at":"2025-03-28T12:32:15.607Z","avatar_url":"https://github.com/CoolCoderSJ.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# HCGateway\r\nHCGateway is a platform to let developers connect to the Health Connect API on Android via a REST API. You can view the documentation for the REST API [here](https://hcgateway.shuchir.dev/)\r\n\r\nThe platform consists of two parts:\r\n- A REST API/server\r\n- A mobile application that pings the server periodically\r\n\r\n## How it Works\r\n- The mobile application pings the server every 2 hours to send data. The following data types are supported-\r\n    - Active Calories Burned (`activeCaloriesBurned`)\r\n    - Basal Body Temperature (`basalBodyTemperature`)\r\n    - Basal Metabolic Rate (`basalMetabolicRate`)\r\n    - Blood Glucose (`bloodGlucose`)\r\n    - Blood Pressure (`bloodPressure`)\r\n    - Body Fat (`bodyFat`)\r\n    - Body Temperature (`bodyTemperature`)\r\n    - Bone Mass (`boneMass`)\r\n    - Cervical Mucus (`cervicalMucus`)\r\n    - Distance (`distance`)\r\n    - Exercise (`exerciseSession`)\r\n    - Elevation Gained (`elevationGained`)\r\n    - Floors Climbed (`floorsClimbed`)\r\n    - Heart Rate (`heartRate`)\r\n    - Height (`height`)\r\n    - Hydration (`hydration`)\r\n    - Lean Body Mass (`leanBodyMass`)\r\n    - Menstruation Flow (`menstruationFlow`)\r\n    - Menstruation Period (`menstruationPeriod`)\r\n    - Nutrition (`nutrition`)\r\n    - Ovulation Test (`ovulationTest`)\r\n    - Oxygen Saturation (`oxygenSaturation`)\r\n    - Power (`power`)\r\n    - Respiratory Rate (`respiratoryRate`)\r\n    - Resting Heart Rate (`restingHeartRate`)\r\n    - Sleep (`sleepSession`)\r\n    - Speed (`speed`)\r\n    - Steps (`steps`)\r\n    - StepsCadence (`stepsCadence`)\r\n    - Total Calories Burned (`totalCaloriesBurned`)\r\n    - VO2 Max (`vo2Max`)\r\n    - Weight (`weight`)\r\n    - Wheelchair Pushes (`wheelchairPushes`)\r\n\r\nSupport for more types is planned for the future.\r\n\r\n- Each sync takes approximatly 15 minutes\r\n- The server encrypts the data using Fernet encryption, then stores it in a database hosted on a custom instance of Appwrite.\r\n- The server exposes an API to let developers login and get the data for their users.\r\n\r\nThe platform is currently a **one way sync**. Any changes made to health connect data by other apps will not be synced. The ability to add/edit/delete data through the api is planned for the future.\r\n\r\n## Get Started\r\n- There is a live instance hosted at https://api.hcgateway.shuchir.dev/ that you can use. You can also host your own instance. To learn more on Self Hosting, skip down to the Self Hosting section.\r\n- You can install the mobile application through the APK file. You can find the latest APK file in the releases section of this repository, or by downloading the `app-release.apk` file from the root of this repository.\r\n- The minimum requirement for the APK file is Android Oreo (8.0)\r\n- Once you install the Android APK file, signup by entering a username and password\r\n- Once you see a screen showing your user id, you have successfully signed up. Your data will sync in 2 hours. This is customizable. You also have the option to force a sync any time through the application.\r\n\r\n## Database\r\n### Users Structure\r\n```\r\nusers {\r\n    name: string\r\n    password: string\r\n}\r\n```\r\n\r\n### Parameters\r\n- `name` - The username of the user\r\n- `password` - The password of the user encrypted using Argon 2 format. The password is never stored as is, and cannot be retrieved through any API.\r\n\r\n### Database Structure\r\n```\r\nuser_id: string {\r\n    type: string {\r\n        $id: string\r\n        $createdAt: datetime\r\n        $updatedAt: datetime\r\n        $permissions: object\r\n        $databaseId: string\r\n        $collectionId: string\r\n        data: string\r\n        id: string\r\n        start: datetime\r\n        end: datetime\r\n        app: string\r\n    }\r\n}\r\n```\r\n\r\n### Parameters\r\n- `$id` - The ID of the object\r\n- `$createdAt` - The date and time the object was added to the database\r\n- `$updatedAt` - The date and time the object was last updated\r\n- `$permissions` - The permissions of the object- will always be []\r\n- `$databaseId` - The ID of the database\r\n- `$collectionId` - The ID of the collection\r\n- `data` - The data of the object encrypted using Fernet. When asked for through the API, the data will be decrypted for you using the user's password found from the user id.\r\n- `id` - The ID of the object- This is the same a  `$id`.\r\n- `start` - The start date and time of the object\r\n- `end` - The end date and time of the object. Might not be present for some objects.\r\n- `app` - The app that the object was synced from.\r\n\r\n\r\n## REST API\r\nThis documentation is also available at https://hcgateway.shuchir.dev/\r\n\r\nThe REST API is a simple Flask application that exposes the following endpoints:\r\n- `/api/login` - Login a user and get the session ID.\r\n    - Method: `POST`\r\n    - Body Parameters:\r\n        - `username` - The username of the user\r\n        - `password` - The password of the user\r\n    - Response:\r\n        - `sessid` - The user ID of the user\r\n\r\n- `/api/sync/\u003cmethod\u003e` - Dump data into the database. **This method is exclusive to the application, and should not be used otherwise.**\r\n    - Method: `POST`\r\n    - Body Parameters:\r\n        - `user` - The user ID of the user\r\n        - `data` - The data to be dumped. \r\n\r\n- `/api/fetch/\u003cmethod\u003e` - Get data from the database.\r\n    - Method: `POST`\r\n    - URL Parameters:\r\n        - `method` - The method to use. The methods are listed above, next to each supported data type under the `How It Works` section. For example, to get all blood glucose data, you would use `/api/fetch/bloodGlucose`.\r\n    - Body Parameters:\r\n        - `userid` - The user ID of the user\r\n        - `queries` - This is an optional parameter. You can filter your response if you'd like. The format is an array of strings, where each string is a query. The following are examples of queries-\r\n            - `limit(num)` - Limit the number of results to `num`, where `num` is an integer. `num` must be less than or equal to 100, otherwise all results will be returned.\r\n            - `equal(\"parameter\", [\"value\"])` - parameter is the name of a parameter; all parameters are listed above, inside of the `type` structure. `value` is an array of values to filter by. For example, `equal(\"id2\", [\"id1\", \"id2\"])` will return all objects that have an id of id1 or id2.\r\n            - `notEqual(\"parameter\", [\"value\"])` - `value` is an array of values to filter by. For example, `notEqual(\"id2\", [\"id1\", \"id2\"])` will return all objects that do not have an id of id1 or id2.\r\n            - `lessThan(\"parameter\", [\"value(s)\"])` - `value` is the value to filter by. For example, `lessThan(\"id\", \"id1\")` will return all objects that have an id less than id1.\r\n            - `greaterThan(\"parameter\", [\"value(s)\"])` - `value` is the value to filter by. For example, `greaterThan(\"id\", \"id1\")` will return all objects that have an id greater than id1.\r\n            - `lessThanEqual(\"parameter\", [\"value(s)\"])` - `value` is the value to filter by. For example, `lessThanEqual(\"id\", \"id1\")` will return all objects that have an id less than or equal to id1.\r\n            - `greaterThanEqual(\"parameter\", [\"value(s)\"])` - `value` is the value to filter by. For example, `greaterThanEqual(\"id\", \"id1\")` will return all objects that have an id greater than or equal to id1.\r\n            - `search(\"parameter\", [\"value\"])` - `value` is the value to search for. For example, `search(\"id\", \"id1\")` will return all objects that have an id that contains id1.\r\n            - `orderDesc(\"parameter\")` - This will order the results in descending order by the parameter. For example, `orderDesc(\"id\")` will return all objects ordered by id in descending order.\r\n            - `orderAsc(\"parameter\")` - This will order the results in ascending order by the parameter. For example, `orderAsc(\"id\")` will return all objects ordered by id in ascending order.\r\n    - Response:\r\n        - `data` - The data retrieved from the database\r\n\r\n## Mobile Application\r\nThe mobile application is a simple Android application that pings the server every 2 hours to send data. It starts a foreground service to do this, and the service will run even if the application is closed. The application is written in React Native.\r\n\r\n## Self Hosting\r\nYou can self host the server and database. To do this, follow the steps below:\r\n- You need Python 3 and NodeJS 18+ installed on your machine\r\n- Install appwrite and make sure your instance is accessible from the machine running the HCGateway server. You can find more at https://appwrite.io/\r\n- Clone this repository\r\n- `cd` into the api/ folder\r\n- run `pip install -r requirements.txt`\r\n- rename `.env.example` to `.env` and fill in the values\r\n- run `python3 main.py` to start the server\r\n\r\nTo run the mobile application:\r\n- in another window/tab, `cd` into the app/ folder\r\n- run `npm install`\r\n- If you wish to remove sentry:\r\n```\r\nyarn remove @sentry/react-native\r\nnpx @sentry/wizard -i reactNative -p android --uninstall\r\n```\r\n- If you wish to change sentry to your own instance:\r\n    - Change the `dsn` in `App.js` to your own DSN\r\n    - Change the server, org name, and project name in app.json\r\n    - Change these details again in android/sentry.properties\r\n    - Change the DSN in the AndroidManifest.xml\r\n- run `npx patch-package` to apply a patch to the foreground service library\r\n- run `npm run android` to start the application, or follow the instructions at https://medium.com/geekculture/react-native-generate-apk-debug-and-release-apk-4e9981a2ea51 to build an APK file.\r\n    - It is also possible to now use eas build to build the APK file. You can find more at https://docs.expo.dev/build/eas-build/ **NOTE: This must be a local build, since you need to run patch-package before building the APK file.**\r\n\r\n---\r\n## Running with Docker\r\n\r\n Running via docker is a great way to ensure that you dont run into env issues.\r\n \r\nTo run the HCGateway API using Docker, follow these steps:\r\n\r\n1. **Prerequisites**\\\r\n    Ensure that you have Docker and Docker Compose installed on your system.\r\n\r\n2. **Setting up Environment Variables**\r\n\r\n   - You’ll need to configure environment variables before starting the services.\r\n   - Copy the provided `.env.example` file to `.env` inside the `api/` directory and configure it as necessary.\r\n\r\n3. **Running the Container (without Docker Compose)**\\\r\n    You can run the container directly using the `docker run` command if you prefer not to use Docker Compose:\r\n\r\n   ```bash\r\n   docker run -itd \\\r\n     -p 6644:6644 \\\r\n     --name hcgateway_api \\\r\n     --env-file ./api/.env \\\r\n     ghcr.io/coolcodersj/hcgateway:latest\r\n   ```\r\n\r\n4. **Running the Containers with Docker Compose**\\\r\n    The project uses Docker Compose for easier container orchestration. To run the API using Docker Compose, run the following command:\r\n    ```bash\r\n   docker-compose up -d\r\n   ```\r\n\r\n6. **Port Configuration**\\\r\n    The API is exposed on port `6644`. You can access the API at:\r\n\r\n   ```\r\n   http://localhost:6644\r\n   ```\r\n   \r\n7. **Container Management**\r\n\r\n   - The container will automatically restart on failures due to the `restart: always` policy.\r\n   - To stop the container, use:\r\n\r\n     ```bash\r\n     docker-compose down\r\n     ```\r\n\r\n9. **Additional Notes**\r\n\r\n   - The Dockerfile uses a Python 3.13 slim image as the base, with all necessary dependencies installed via `requirements.txt`.\r\n   - If any changes are made to the `Dockerfile` or dependencies, rerun the command with the `--build` flag to rebuild the images.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCoolCoderSJ%2FHCGateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCoolCoderSJ%2FHCGateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCoolCoderSJ%2FHCGateway/lists"}