HabitForge/ZEPP_IMPORT.md

HabitForge - Zepp Data Import

Overview

This document explains how to import your Zepp/Mi Band/Amazfit health data into HabitForge.

Prerequisites

• Zepp data export in export-zepp/ directory (exported from Zepp app)
• HabitForge application running
• User account created in HabitForge

Export Structure

Your Zepp export should be in the following structure:

export-zepp/
└── [ACCOUNT_ID_TIMESTAMP]/
    ├── ACTIVITY/         # Daily activity summaries (steps, distance, calories)
    ├── ACTIVITY_MINUTE/  # Minute-by-minute activity data
    ├── ACTIVITY_STAGE/   # Activity segments
    ├── BODY/             # Body measurements (weight, BMI, etc.)
    ├── HEALTH_DATA/      # Additional health metrics
    ├── HEARTRATE/        # Manual heart rate readings
    ├── HEARTRATE_AUTO/   # Automatic heart rate monitoring
    ├── SLEEP/            # Sleep summaries
    ├── SLEEP_MINUTE/     # Minute-by-minute sleep data
    ├── SPORT/            # Workout/sport sessions
    └── USER/             # User profile data

Import Process

Option 1: Using Docker (Recommended)

docker-compose -f docker-compose.dev.yml exec web python scripts/import_zepp_data.py

Option 2: Local Environment

python scripts/import_zepp_data.py

Specify User ID

If you need to import data for a specific user:

python scripts/import_zepp_data.py --user-id 2

Data Imported

Daily Health Metrics

• Activity: Steps, distance (meters), calories burned
• Sleep: Total sleep time, deep sleep, light sleep, REM sleep, awake duration
• Heart Rate: Average, minimum, maximum, resting heart rate
• Body: Weight measurements
• PAI Score: Calculated from activity and heart rate data

Workout Sessions

• Running (type 1)
• Walking (type 6)
• Cycling (type 8)
• Elliptical (type 10)
• Free Training (type 16)
• HIIT (type 23)
• Stretching (type 52)
• Yoga (type 60)

Each workout includes:

• Start/end time
• Duration
• Distance
• Calories burned
• Pace metrics (avg, min, max)

API Endpoints

After importing, you can access the data via these endpoints:

Health Stats

GET /api/health/stats?period=week
GET /api/health/stats?period=month
GET /api/health/stats?period=year

Workout Sessions

GET /api/health/workouts              # List workouts
GET /api/health/workouts/summary      # Workout statistics

Notes

• The import will merge data with existing records (taking the imported values for conflicts)
• Default user ID is 1
• The script automatically finds the latest export directory
• All timestamps are converted to local dates for daily aggregation
• PAI scores are calculated automatically based on activity and heart rate data

Re-importing Data

If you export new data from Zepp, simply replace the contents of export-zepp/ and run the import script again. It will upsert (update or insert) all records.