# RunCalculator Pro - Full Documentation

> Free online calculator for planning runs and walks with interactive map, calorie calculation, and route export

## Overview

RunCalculator Pro is a comprehensive Progressive Web App (PWA) designed for runners, joggers, and walkers who want to plan their routes and track fitness metrics. The application provides an interactive map interface for route creation, accurate calorie calculations using the MET formula, and multiple export options for GPS devices.

### Key Differentiators

- **No Registration Required**: Start using immediately without creating an account
- **100% Free**: No premium tiers, no hidden costs, no subscriptions
- **Privacy-First**: All data stored locally in browser's IndexedDB
- **Offline Capable**: Works without internet after initial load
- **Multilingual**: Full support for 5 languages (EN, RU, ES, ZH, JA)
- **Open Map Data**: Uses OpenStreetMap (free and open-source)

---

## Core Features

### 1. Interactive Route Building

**Technology**: Leaflet + React-Leaflet + OpenStreetMap + OSRM

Users can create running/walking routes by clicking on the map:
- Click to add waypoints
- Drag waypoints to adjust route
- Double-click to remove waypoints
- Route automatically follows roads and paths via OSRM
- Real-time distance calculation
- Elevation data from Open-Elevation API

**Supported Interactions**:
- Touch gestures on mobile
- Zoom with scroll/pinch
- Geolocation for current position
- Undo/redo waypoint actions

### 2. Calorie Calculator

**Formula**: MET (Metabolic Equivalent of Task) method

**Base Formula**:
```
Calories = MET × Weight(kg) × Duration(hours) + Elevation_Calories
```

**Detailed MET Values** (based on Compendium of Physical Activities):

*Walking MET Values*:
- 3 km/h or slower: 2.0 MET
- 4 km/h: 3.0 MET
- 5 km/h: 3.5 MET
- 6 km/h: 5.0 MET
- 7 km/h: 6.3 MET
- Linear interpolation between speeds for accuracy

*Running MET Values*:
- 7 km/h: 7.0 MET
- 8 km/h: 8.0 MET
- 9 km/h: 9.0 MET
- 10 km/h: 10.0 MET
- 11 km/h: 11.0 MET
- 12 km/h: 11.5 MET
- 13 km/h: 12.5 MET
- 14 km/h: 13.5 MET
- 16 km/h: 15.0 MET
- 18 km/h: 16.0 MET
- Linear interpolation between speeds for accuracy

**Elevation Adjustments**:
```
Elevation_Calories = (Elevation_Gain(m) / 100) × 0.5 × Weight(kg) + (Elevation_Loss(m) / 100) × 0.2 × Weight(kg)
```
- Ascent: ~0.5 kcal per kg per 100m climbing
- Descent: ~0.2 kcal per kg per 100m (eccentric muscle work)

**Age Adjustment**:
```
Age_Multiplier = 
  age < 30: 1.0
  age < 40: 0.98
  age < 50: 0.96
  age < 60: 0.94
  age >= 60: 0.92
```

**Gender Adjustment**:
```
Gender_Multiplier = 
  male: 1.05
  female: 0.95
  other: 1.0
```

**Complete Formula**:
```
Calories = (MET × Weight × Duration_Hours × Age_Multiplier × Gender_Multiplier) + Elevation_Calories
```

### 3. Duration Estimation

**Formula**: Based on Naismith's rule with modifications for running

**Base Duration Calculation**:
```
Base_Duration(minutes) = Distance(km) × Pace(min/km)
```
OR
```
Base_Duration(minutes) = (Distance(km) / Speed(km/h)) × 60
```

**Default Speeds by Fitness Level**:
- Walking: Beginner 4.0 km/h, Intermediate 5.0 km/h, Advanced 6.0 km/h
- Running: Beginner 7.0 km/h, Intermediate 9.0 km/h, Advanced 12.0 km/h

**Elevation Penalties** (additional time per 100m):
```
Elevation_Penalty = (Elevation_Gain(m) / 100) × Penalty_Up × Fitness_Modifier + (Elevation_Loss(m) / 100) × Penalty_Down × Fitness_Modifier
```

*Walking Penalties*:
- Up: +10 minutes per 100m
- Down: +2 minutes per 100m

*Running Penalties*:
- Up: +6 minutes per 100m
- Down: +1.5 minutes per 100m

**Fitness Level Modifiers**:
```
Fitness_Modifier = 
  beginner: 1.3 (30% more time)
  intermediate: 1.0 (normal)
  advanced: 0.7 (30% less time)
```

**Age Adjustment** (for age > 40):
```
Age_Adjustment = 1 + (Age - 40) × 0.005
```
(0.5% slower per year over 40)

**Complete Formula**:
```
Total_Duration = (Base_Duration + Elevation_Penalty) × Age_Adjustment
```

### 4. Steps Calculator

**Stride Length Calculation**:

**Base Coefficients**:
```
Base_Stride_Length(cm) = Height(cm) × Coefficient
```
- Walking coefficient: 0.413 (41.3% of height)
- Running coefficient: 0.65 (65% of height)

**Gender Modifier**:
```
Gender_Modifier = 
  male: 1.02 (2% longer stride)
  female: 0.98 (2% shorter stride)
  other: 1.0
```

**Pace Modifier** (affects stride length):

*Walking*:
- Pace ≥ 15 min/km: 0.95
- Pace ≥ 12 min/km: 1.0
- Pace ≥ 10 min/km: 1.05
- Pace < 10 min/km: 1.1

*Running*:
- Pace ≥ 8 min/km: 0.9
- Pace ≥ 6 min/km: 1.0
- Pace ≥ 5 min/km: 1.1
- Pace < 5 min/km: 1.2

**Complete Stride Length Formula**:
```
Stride_Length(cm) = Height(cm) × Coefficient × Gender_Modifier × Pace_Modifier
```

**Steps Calculation**:
```
Steps = Distance(m) / (Stride_Length(cm) / 100)
```

**Cadence Calculation** (steps per minute):
```
Speed(m/min) = 1000 / Pace(min/km)
Cadence(spm) = Speed(m/min) / Stride_Length(m)
```

**Optimal Cadence Ranges**:
- Walking: 100-130 steps per minute
- Running: 160-190 steps per minute

### 5. Elevation Profile

- SVG-based visualization
- Shows elevation changes along route
- Highlights climbs and descents
- Total elevation gain/loss statistics

### 6. Export Options

**GPX Export**: Standard GPS Exchange Format
- Compatible with Garmin, Strava, Komoot, etc.
- Includes waypoints and track data

**KML Export**: Keyhole Markup Language
- Compatible with Google Earth
- Includes route visualization data

**External Links**:
- Open in Google Maps
- Open in Yandex Maps
- Copy shareable link

### 7. Route Storage

**Technology**: IndexedDB via idb library

- Save up to 100 routes locally
- No server storage (privacy-first)
- Import GPX/KML files
- Filter routes by distance/date
- Route preview with map thumbnail

---

## Pages and Navigation

### Home Page (/https://runcalculator.pro/en)
Main application interface with:
- Interactive map (full screen on mobile)
- Calculator panel (sidebar on desktop, bottom sheet on mobile)
- Export controls
- Results display with animated counters

### About Page (https://runcalculator.pro/en/about)
Information about the project:
- How to use the calculator
- Feature explanations
- FAQ section with JSON-LD markup

### Tips Page (https://runcalculator.pro/en/tips)
Running tips for beginners:
- Warming up correctly
- Proper running technique
- Recovery guidelines
- Common mistakes to avoid
- HowTo structured data for search engines

### Routes Page (https://runcalculator.pro/en/routes)
Saved routes management:
- List of saved routes
- Import GPX/KML files
- Delete routes
- Load route to map

### Terms of Service (https://runcalculator.pro/en/terms)
Legal terms for using the service

### Privacy Policy (https://runcalculator.pro/en/privacy)
Data handling and privacy information:
- What data is collected (none on server)
- How data is stored (locally in browser)
- Third-party services (maps, analytics)

---

## User Input Parameters

### Required Fields
| Field | Range | Default |
|-------|-------|---------|
| Weight | 30-300 kg | 70 kg |
| Height | 100-250 cm | 170 cm |
| Age | 10-100 years | 30 |
| Activity Type | walking/running | running |

### Optional Fields
| Field | Options | Default |
|-------|---------|---------|
| Gender | male/female | - |
| Fitness Level | beginner/intermediate/advanced | intermediate |
| Target Pace | 3-20 min/km | auto-calculated |

---

## Technical Architecture

### Frontend Stack
- **Framework**: Next.js 15 (App Router)
- **Language**: TypeScript 5.x
- **Styling**: Tailwind CSS 4
- **State**: Zustand
- **Animation**: Framer Motion
- **i18n**: next-intl (5 locales)
- **Icons**: Lucide React

### Map Stack
- **Map Library**: Leaflet + React-Leaflet
- **Tiles**: OpenStreetMap
- **Routing**: OSRM (Open Source Routing Machine)
- **Elevation**: Open-Elevation API

### Data Storage
- **Client Storage**: IndexedDB (via idb)
- **No Server Database**: Privacy-first design
- **User Settings**: localStorage
- **Routes**: IndexedDB with max 100 routes

### PWA Features
- **Service Worker**: next-pwa
- **Offline Support**: Cached assets + saved routes
- **Install Prompt**: Add to home screen
- **Map Caching**: Frequently used tiles cached

---

## API Endpoints

### Internal API Endpoints

#### 1. Route Calculation API
`POST https://runcalculator.pro/api/route`

**Purpose**: Calculate route between waypoints using OSRM routing engine

**Request Body**:
```json
{
  "points": [
    { "lat": 55.7558, "lng": 37.6173 },
    { "lat": 55.7600, "lng": 37.6200 },
    { "lat": 55.7650, "lng": 37.6250 }
  ],
  "profile": "foot" // or "bike"
}
```

**Request Parameters**:
- `points` (required): Array of coordinate objects with `lat` (latitude) and `lng` (longitude)
  - Minimum: 2 points
  - Maximum: 25 points (OSRM limitation)
- `profile` (optional): Routing profile
  - `"foot"`: For running/walking (default)
  - `"bike"`: For cycling

**Response**:
```json
{
  "polyline": "encoded_polyline_string",
  "coordinates": [
    [55.7558, 37.6173],
    [55.7559, 37.6174],
    ...
  ],
  "distance": 1234.5, // meters
  "duration": 567.8   // seconds (estimated walking time)
}
```

**Response Fields**:
- `polyline`: Encoded polyline string (Google's polyline algorithm format)
- `coordinates`: Array of [lat, lng] coordinate pairs along the route
- `distance`: Total route distance in meters
- `duration`: Estimated travel time in seconds (based on walking speed)

**Limitations**:
- Maximum 25 waypoints per request (OSRM limit)
- Requires at least 2 points
- Profile options: "foot" (for running/walking) or "bike"
- OSRM service may have rate limits
- Routes follow roads and paths (no off-road routing)

**Error Responses**:
- `400 Bad Request`: Invalid request
  ```json
  {
    "error": "At least 2 points required",
    "code": "INVALID_REQUEST"
  }
  ```
- `404 Not Found`: No route found between points
  ```json
  {
    "error": "No route found",
    "code": "NO_ROUTE"
  }
  ```
- `500 Internal Server Error`: Server or OSRM service error
  ```json
  {
    "error": "Internal server error",
    "code": "SERVER_ERROR"
  }
  ```

**Example Usage**:
```bash
# Simple 2-point route
curl -X POST https://runcalculator.pro/api/route \
  -H "Content-Type: application/json" \
  -d '{
    "points": [
      {"lat": 55.7558, "lng": 37.6173},
      {"lat": 55.7600, "lng": 37.6200}
    ],
    "profile": "foot"
  }'

# Multi-point route
curl -X POST https://runcalculator.pro/api/route \
  -H "Content-Type: application/json" \
  -d '{
    "points": [
      {"lat": 55.7558, "lng": 37.6173},
      {"lat": 55.7600, "lng": 37.6200},
      {"lat": 55.7650, "lng": 37.6250},
      {"lat": 55.7700, "lng": 37.6300}
    ],
    "profile": "foot"
  }'
```

**Technical Details**:
- Uses OSRM (Open Source Routing Machine) public API
- Polyline encoding uses Google's algorithm (compressed coordinate representation)
- Route geometry follows actual roads and paths
- Distance calculation accounts for road curvature
- Duration is estimated based on walking speed (does not account for running pace)

#### 2. Elevation API
`POST https://runcalculator.pro/api/elevation`

**Purpose**: Get elevation data for route points

**Request Body**:
```json
{
  "points": [
    { "lat": 55.7558, "lng": 37.6173 },
    { "lat": 55.7600, "lng": 37.6200 },
    { "lat": 55.7650, "lng": 37.6250 }
  ]
}
```

**Request Parameters**:
- `points` (required): Array of coordinate objects
  - Minimum: 1 point
  - Maximum: 100 points per request
  - Each point must have `lat` and `lng` properties

**Response**:
```json
{
  "elevations": [156.2, 158.5, 162.3] // meters above sea level
}
```

**Response Fields**:
- `elevations`: Array of elevation values in meters above sea level
  - Array length matches input points array
  - Values are in same order as input points
  - Values are floats with 1 decimal precision

**Limitations**:
- Maximum 100 points per request
- Uses Open-Elevation API (primary) with fallback to Open-Meteo API
- Elevation data accuracy: ±5-10 meters (varies by location)
- May be slower for large point arrays
- Some remote locations may have less accurate data

**Error Responses**:
- `400 Bad Request`: Invalid request
  ```json
  {
    "error": "Points array cannot be empty",
    "code": "INVALID_REQUEST"
  }
  ```
- `503 Service Unavailable`: All elevation APIs failed
  ```json
  {
    "error": "Elevation service unavailable",
    "code": "SERVICE_UNAVAILABLE"
  }
  ```
- `500 Internal Server Error`: Internal error
  ```json
  {
    "error": "Internal server error",
    "code": "SERVER_ERROR"
  }
  ```

**Example Usage**:
```bash
# Single point elevation
curl -X POST https://runcalculator.pro/api/elevation \
  -H "Content-Type: application/json" \
  -d '{
    "points": [
      {"lat": 55.7558, "lng": 37.6173}
    ]
  }'

# Multiple points elevation
curl -X POST https://runcalculator.pro/api/elevation \
  -H "Content-Type: application/json" \
  -d '{
    "points": [
      {"lat": 55.7558, "lng": 37.6173},
      {"lat": 55.7600, "lng": 37.6200},
      {"lat": 55.7650, "lng": 37.6250}
    ]
  }'
```

**Technical Details**:
- Primary API: Open-Elevation (https://api.open-elevation.com/api/v1/lookup)
- Fallback API: Open-Meteo Elevation API
- Data source: SRTM (Shuttle Radar Topography Mission) and other DEM datasets
- Elevation values are relative to sea level (EGM96 geoid)
- Batch requests are more efficient than individual requests

#### 3. Health Check API
`GET https://runcalculator.pro/api/health`

**Purpose**: Service health monitoring and status check

**Request**: No parameters required

**Response**:
```json
{
  "status": "ok",
  "timestamp": "2026-02-10T12:00:00.000Z",
  "version": "0.1.0",
  "uptime": 1234567 // seconds (optional)
}
```

**Response Fields**:
- `status`: Service status ("ok", "degraded", "down")
- `timestamp`: Current server time in ISO 8601 format
- `version`: Application version string
- `uptime`: Server uptime in seconds (optional)

**Example Usage**:
```bash
curl https://runcalculator.pro/api/health
```

**Use Cases**:
- Monitoring service availability
- Load balancer health checks
- CI/CD pipeline health verification
- Status page integration

### Public Endpoints

#### Sitemap
`GET https://runcalculator.pro/sitemap.xml`
XML sitemap with all pages in all languages

#### Robots.txt
`GET https://runcalculator.pro/robots.txt`
Crawler directives for search engines and AI bots

#### LLMs.txt
`GET https://runcalculator.pro/llms.txt`
AI-friendly site summary (short version of this document)

#### LLMs Full Documentation
`GET https://runcalculator.pro/.well-known/llms-full.txt`
Extended documentation (this file)

---

## Localization

### Supported Languages
| Code | Language | Native Name |
|------|----------|-------------|
| en | English | English |
| ru | Russian | Русский |
| es | Spanish | Español |
| zh | Chinese | 中文 |
| ja | Japanese | 日本語 |

### URL Structure
`/{locale}/page-name`
Example: `/ru/about`, `/ja/tips`

---

## Structured Data

The application includes JSON-LD structured data for:
- **WebApplication**: App metadata for search engines
- **Organization**: Brand information
- **BreadcrumbList**: Navigation path
- **FAQPage**: Common questions (About page)
- **HowTo**: Step-by-step guides (Tips page)

---

## Accuracy Disclaimer

Calorie and distance calculations are estimates based on scientific formulas. Actual values may vary based on:
- Individual metabolism
- Running technique
- Weather conditions
- Surface type (trail vs road)
- Equipment weight

Always consult a healthcare professional before starting a new exercise program.

---

## Contact & Links

- Website: https://runcalculator.pro
- Sitemap: https://runcalculator.pro/sitemap.xml
- Health Check: https://runcalculator.pro/api/health

---

## Data Structures

### Route Data Structure
```typescript
interface RoutePoint {
  lat: number;           // Latitude in decimal degrees (-90 to 90)
  lng: number;           // Longitude in decimal degrees (-180 to 180)
  elevation: number | null; // Elevation in meters above sea level (nullable, null if not fetched)
}

interface Route {
  id: string;            // Unique route identifier (UUID v4 format)
  name: string;          // User-defined route name (max 100 characters)
  createdAt: number;     // Timestamp in milliseconds since Unix epoch
  updatedAt: number;     // Timestamp in milliseconds since Unix epoch
  points: RoutePoint[];  // Array of waypoints (minimum 2 points)
  polyline: string;      // Encoded polyline string (Google's polyline algorithm)
  distance: number;      // Total distance in meters (calculated from route geometry)
  elevationGain: number; // Total elevation gain in meters (sum of positive elevation changes)
  elevationLoss: number; // Total elevation loss in meters (sum of negative elevation changes)
  activityType: 'walking' | 'running';
}
```

**Example Route Object**:
```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Morning Run - Central Park",
  "createdAt": 1707484800000,
  "updatedAt": 1707484800000,
  "points": [
    {"lat": 55.7558, "lng": 37.6173, "elevation": 156.2},
    {"lat": 55.7600, "lng": 37.6200, "elevation": 158.5},
    {"lat": 55.7650, "lng": 37.6250, "elevation": 162.3}
  ],
  "polyline": "y~{xG}~|bM_@qA",
  "distance": 5234.5,
  "elevationGain": 45.2,
  "elevationLoss": 12.8,
  "activityType": "running"
}
```

### User Parameters Structure
```typescript
interface UserParams {
  weight: number;        // Weight in kg (range: 30-300)
  height: number;        // Height in cm (range: 100-250)
  age: number;          // Age in years (range: 10-100)
  gender?: 'male' | 'female' | 'other'; // Optional gender for more accurate calculations
  fitnessLevel: 'beginner' | 'intermediate' | 'advanced'; // Fitness level affects default speeds
  pace?: number;        // Custom pace in min/km (optional, range: 3-20)
  activityType: 'walking' | 'running'; // Type of activity
}
```

**Example User Parameters**:
```json
{
  "weight": 70,
  "height": 175,
  "age": 30,
  "gender": "male",
  "fitnessLevel": "intermediate",
  "pace": 6,
  "activityType": "running"
}
```

**Validation Rules**:
- Weight: Must be between 30 and 300 kg
- Height: Must be between 100 and 250 cm
- Age: Must be between 10 and 100 years
- Pace: If provided, must be between 3 and 20 min/km
- Gender: Optional, defaults to 'other' if not specified
- Fitness Level: Affects default speeds:
  - Walking: beginner=4.0, intermediate=5.0, advanced=6.0 km/h
  - Running: beginner=7.0, intermediate=9.0, advanced=12.0 km/h

### Calculation Results Structure
```typescript
interface CalculationMetrics {
  distance: number;      // Distance in km (rounded to 2 decimal places)
  duration: number;      // Duration in minutes (rounded to nearest integer)
  calories: number;       // Calories burned in kcal (rounded to nearest integer)
  steps: number;         // Total steps (rounded to nearest integer)
  avgPace: number;       // Average pace in min/km (rounded to 2 decimal places)
  intensity: 'light' | 'moderate' | 'high'; // Activity intensity level
  elevationGain: number; // Total elevation gain in meters (rounded to 1 decimal)
  elevationLoss: number; // Total elevation loss in meters (rounded to 1 decimal)
  cadence?: number;      // Steps per minute (optional, calculated if pace provided)
  strideLength?: number; // Stride length in cm (optional, calculated if height provided)
}
```

**Example Calculation Results**:
```json
{
  "distance": 5.23,
  "duration": 33,
  "calories": 388,
  "steps": 3825,
  "avgPace": 6.31,
  "intensity": "moderate",
  "elevationGain": 45.2,
  "elevationLoss": 12.8,
  "cadence": 144,
  "strideLength": 131.3
}
```

**Intensity Levels**:
- `light`: Low-intensity activity (walking at slow pace, easy jogging)
- `moderate`: Moderate-intensity activity (brisk walking, moderate running)
- `high`: High-intensity activity (fast running, sprinting)

### Goal Estimation Structure
```typescript
interface GoalEstimation {
  distance: number;      // Suggested distance in km
  duration: number;       // Estimated duration in minutes
  calories: number;       // Estimated calories burned
  elevationGain: number;  // Estimated elevation gain in meters
  suggestedPace: number;  // Suggested pace in min/km
}
```

**Example Goal Estimation**:
```json
{
  "distance": 7.7,
  "duration": 51,
  "calories": 500,
  "elevationGain": 0,
  "suggestedPace": 6.67
}
```

### Route Option Structure (for goal-based route generation)
```typescript
interface RouteOption {
  name: string;          // Option name: "fast", "balanced", "easy"
  intensity: 'light' | 'moderate' | 'high';
  distance: number;      // Distance in km
  duration: number;      // Duration in minutes
  calories: number;      // Calories in kcal
  suggestedPace: number; // Suggested pace in min/km
}
```

**Example Route Options**:
```json
[
  {
    "name": "fast",
    "intensity": "high",
    "distance": 6.2,
    "duration": 31,
    "calories": 500,
    "suggestedPace": 5.0
  },
  {
    "name": "balanced",
    "intensity": "moderate",
    "distance": 7.7,
    "duration": 51,
    "calories": 500,
    "suggestedPace": 6.67
  },
  {
    "name": "easy",
    "intensity": "light",
    "distance": 9.5,
    "duration": 81,
    "calories": 500,
    "suggestedPace": 8.53
  }
]
```

## Example User Queries and Responses

### Query 1: "How many calories will I burn running 5km?"
**User Input**:
- Weight: 70 kg
- Height: 175 cm
- Age: 30
- Gender: Male
- Activity: Running
- Distance: 5 km
- Pace: 6 min/km (10 km/h)
- Elevation: 50m gain, 20m loss

**Calculation Process**:
1. Speed: 10 km/h
2. MET: 10.0 (for 10 km/h running, linear interpolation between 9 km/h = 9.0 MET and 10 km/h = 10.0 MET)
3. Duration: 5 km / 10 km/h = 0.5 hours = 30 minutes
4. Base Calories: 10.0 × 70 × 0.5 = 350 kcal
5. Age Adjustment: 30 < 30, multiplier = 1.0, calories remain 350 kcal
6. Gender Adjustment: Male multiplier = 1.05, calories = 350 × 1.05 = 367.5 kcal
7. Elevation Calories:
   - Ascent: (50/100) × 0.5 × 70 = 17.5 kcal
   - Descent: (20/100) × 0.2 × 70 = 2.8 kcal
   - Total elevation: 17.5 + 2.8 = 20.3 kcal
8. Total: 367.5 + 20.3 = 387.8 ≈ 388 kcal

**Response**: "Running 5km at 10 km/h (6 min/km pace) will burn approximately **388 calories**."

### Query 2: "How long will it take to walk 3km?"
**User Input**:
- Activity: Walking
- Distance: 3 km
- Fitness Level: Intermediate
- Age: 45
- Elevation: 100m gain, 50m loss

**Calculation Process**:
1. Default Speed: 5.0 km/h (intermediate walking)
2. Base Duration: 3 km / 5.0 km/h = 0.6 hours = 36 minutes
3. Elevation Penalties:
   - Up penalty: (100/100) × 10 × 1.0 = 10 minutes
   - Down penalty: (50/100) × 2 × 1.0 = 1 minute
   - Total elevation penalty: 11 minutes
4. Total before age: 36 + 11 = 47 minutes
5. Age Adjustment: Age 45 > 40, adjustment = 1 + (45 - 40) × 0.005 = 1.025
6. Final Duration: 47 × 1.025 = 48.175 ≈ 48 minutes

**Response**: "Walking 3km with 100m elevation gain will take approximately **48 minutes**."

### Query 3: "How many steps in 10km run?"
**User Input**:
- Height: 180 cm
- Activity: Running
- Distance: 10 km
- Gender: Male
- Pace: 5 min/km (12 km/h)

**Calculation Process**:
1. Base Stride Coefficient: 0.65 (running)
2. Base Stride: 180 × 0.65 = 117 cm
3. Gender Modifier: Male = 1.02, stride = 117 × 1.02 = 119.34 cm
4. Pace Modifier: Pace 5 min/km < 5 min/km, modifier = 1.2, stride = 119.34 × 1.2 = 143.21 cm
5. Stride Length: 143.21 cm = 1.4321 m
6. Steps: (10 × 1000) / 1.4321 = 6,983 steps

**Response**: "Running 10km at 5 min/km pace will take approximately **6,983 steps**."

### Query 4: "What distance do I need to run to burn 500 calories?"
**User Input**:
- Weight: 65 kg
- Activity: Running
- Fitness Level: Intermediate
- Age: 35
- Gender: Female
- Target Calories: 500 kcal
- Elevation: Flat terrain (0m per km)

**Calculation Process**:
1. Default Speed: 9 km/h (intermediate running)
2. MET: 9.0 (for 9 km/h running)
3. Age Adjustment: 35 < 40, age multiplier = 0.98
4. Gender Adjustment: Female multiplier = 0.95
5. Effective MET: 9.0 × 0.98 × 0.95 = 8.379
6. Hours per km: 1 / 9 = 0.111 hours/km
7. Calories per km: 8.379 × 65 × 0.111 = 60.4 kcal/km
8. Distance: 500 / 60.4 = 8.28 km

**Response**: "To burn 500 calories, you need to run approximately **8.3 km** at intermediate pace."

### Query 5: "Generate a 5km loop route starting from my location"
**User Input**:
- Start Point: User's current location (55.7558°N, 37.6173°E)
- Target Distance: 5 km
- Route Type: Loop
- Activity: Running
- Weight: 70 kg, Height: 175 cm, Age: 30

**Process**:
1. Generate waypoints in circular pattern around start point (4-6 waypoints)
2. Call OSRM API: POST to https://router.project-osrm.org/route/v1/foot/37.6173,55.7558;37.6200,55.7600;...
3. Receive polyline-encoded route with distance and duration
4. Calculate actual distance: 4.8 km (slightly less than target)
5. Adjust waypoints outward to increase distance to ~5.0 km
6. Fetch elevation data: POST to elevation API with route coordinates
7. Calculate metrics:
   - Distance: 5.0 km
   - Elevation gain: 45m, loss: 38m
   - Duration: ~33 minutes (at 9 km/h intermediate pace)
   - Calories: ~365 kcal
   - Steps: ~3,850 steps

**Response**: Returns route with:
- Actual distance: 5.0 km
- Estimated duration: 33 minutes
- Estimated calories: 365 kcal
- Estimated steps: 3,850 steps
- Elevation profile: 45m gain, 38m loss
- GPX/KML export available

### Query 6: "How long to burn 300 calories walking?"
**User Input**:
- Weight: 60 kg
- Activity: Walking
- Fitness Level: Beginner
- Age: 25
- Gender: Female
- Target Calories: 300 kcal

**Calculation Process**:
1. Default Speed: 4.0 km/h (beginner walking)
2. MET: 3.0 (for 4 km/h walking)
3. Age Adjustment: 25 < 30, multiplier = 1.0
4. Gender Adjustment: Female multiplier = 0.95
5. Effective MET: 3.0 × 1.0 × 0.95 = 2.85
6. Calories per hour: 2.85 × 60 = 171 kcal/hour
7. Duration: 300 / 171 = 1.754 hours = 105 minutes = 1 hour 45 minutes
8. Distance covered: 4.0 × 1.754 = 7.02 km

**Response**: "To burn 300 calories walking at beginner pace, you need to walk for approximately **1 hour 45 minutes** (about **7 km**)."

### Query 7: "Calculate steps for a 2km walk with elevation"
**User Input**:
- Height: 165 cm
- Activity: Walking
- Distance: 2 km
- Gender: Female
- Pace: 12 min/km (5 km/h)
- Elevation: 80m gain

**Calculation Process**:
1. Base Stride Coefficient: 0.413 (walking)
2. Base Stride: 165 × 0.413 = 68.145 cm
3. Gender Modifier: Female = 0.98, stride = 68.145 × 0.98 = 66.782 cm
4. Pace Modifier: Pace 12 min/km ≥ 12 min/km, modifier = 1.0, stride = 66.782 cm
5. Stride Length: 66.782 cm = 0.66782 m
6. Steps: (2 × 1000) / 0.66782 = 2,996 steps

**Response**: "Walking 2km at 12 min/km pace will take approximately **2,996 steps**."

### Query 8: "What's my cadence running at 6 min/km?"
**User Input**:
- Height: 175 cm
- Activity: Running
- Pace: 6 min/km (10 km/h)
- Gender: Male

**Calculation Process**:
1. Base Stride: 175 × 0.65 = 113.75 cm
2. Gender Modifier: 113.75 × 1.02 = 116.025 cm
3. Pace Modifier: Pace 6 min/km ≥ 6 min/km, modifier = 1.0
4. Stride Length: 116.025 cm = 1.16025 m
5. Speed in m/min: 1000 / 6 = 166.67 m/min
6. Cadence: 166.67 / 1.16025 = 143.7 ≈ 144 steps per minute

**Response**: "Running at 6 min/km pace, your cadence will be approximately **144 steps per minute** (within optimal range of 160-190 for running)."

### Query 9: "Generate route to burn 400 calories"
**User Input**:
- Weight: 75 kg
- Activity: Running
- Fitness Level: Advanced
- Age: 28
- Gender: Male
- Target Calories: 400 kcal
- Start Point: Current location

**Calculation Process**:
1. Default Speed: 12 km/h (advanced running)
2. MET: 11.5 (for 12 km/h running, linear interpolation)
3. Age Adjustment: 28 < 30, multiplier = 1.0
4. Gender Adjustment: Male multiplier = 1.05
5. Effective MET: 11.5 × 1.0 × 1.05 = 12.075
6. Hours per km: 1 / 12 = 0.0833 hours/km
7. Calories per km: 12.075 × 75 × 0.0833 = 75.4 kcal/km
8. Distance: 400 / 75.4 = 5.3 km
9. Duration: 5.3 / 12 × 60 = 26.5 minutes

**Response**: "To burn 400 calories, generate a **5.3 km** route. At advanced running pace, this will take approximately **27 minutes**."

### Query 10: "Calculate calories for hilly 8km run"
**User Input**:
- Weight: 68 kg
- Height: 172 cm
- Age: 42
- Gender: Male
- Activity: Running
- Distance: 8 km
- Pace: 5.5 min/km (10.9 km/h)
- Elevation: 250m gain, 180m loss

**Calculation Process**:
1. Speed: 10.9 km/h
2. MET: Linear interpolation between 10 km/h (10.0 MET) and 11 km/h (11.0 MET)
   - MET = 10.0 + (10.9 - 10.0) × (11.0 - 10.0) / (11.0 - 10.0) = 10.9 MET
3. Duration: 8 / 10.9 = 0.734 hours = 44 minutes
4. Base Calories: 10.9 × 68 × 0.734 = 544.1 kcal
5. Age Adjustment: 42 < 50, multiplier = 0.96, calories = 544.1 × 0.96 = 522.3 kcal
6. Gender Adjustment: Male multiplier = 1.05, calories = 522.3 × 1.05 = 548.4 kcal
7. Elevation Calories:
   - Ascent: (250/100) × 0.5 × 68 = 85 kcal
   - Descent: (180/100) × 0.2 × 68 = 24.5 kcal
   - Total: 85 + 24.5 = 109.5 kcal
8. Total: 548.4 + 109.5 = 657.9 ≈ 658 kcal

**Response**: "Running 8km with 250m elevation gain will burn approximately **658 calories** and take about **44 minutes**."

## Detailed Calculation Formulas

### Complete Calorie Calculation Formula

**Step-by-step process**:

1. **Calculate Speed**:
   ```
   Speed(km/h) = Distance(km) / Duration_Hours
   OR
   Speed(km/h) = 60 / Pace(min/km)
   ```

2. **Get MET Value** (with linear interpolation):
   ```
   For Walking:
   - If speed ≤ 3 km/h: MET = 2.0
   - If 3 < speed ≤ 4: MET = linear_interpolate(3, 2.0, 4, 3.0, speed)
   - If 4 < speed ≤ 5: MET = linear_interpolate(4, 3.0, 5, 3.5, speed)
   - If 5 < speed ≤ 6: MET = linear_interpolate(5, 3.5, 6, 5.0, speed)
   - If 6 < speed ≤ 7: MET = linear_interpolate(6, 5.0, 7, 6.3, speed)
   - If speed > 7: MET = 6.3
   
   For Running:
   - If speed ≤ 7 km/h: MET = 7.0
   - If 7 < speed ≤ 8: MET = linear_interpolate(7, 7.0, 8, 8.0, speed)
   - If 8 < speed ≤ 9: MET = linear_interpolate(8, 8.0, 9, 9.0, speed)
   - If 9 < speed ≤ 10: MET = linear_interpolate(9, 9.0, 10, 10.0, speed)
   - If 10 < speed ≤ 11: MET = linear_interpolate(10, 10.0, 11, 11.0, speed)
   - If 11 < speed ≤ 12: MET = linear_interpolate(11, 11.0, 12, 11.5, speed)
   - If 12 < speed ≤ 13: MET = linear_interpolate(12, 11.5, 13, 12.5, speed)
   - If 13 < speed ≤ 14: MET = linear_interpolate(13, 12.5, 14, 13.5, speed)
   - If 14 < speed ≤ 16: MET = linear_interpolate(14, 13.5, 16, 15.0, speed)
   - If 16 < speed ≤ 18: MET = linear_interpolate(16, 15.0, 18, 16.0, speed)
   - If speed > 18: MET = 16.0
   
   Linear Interpolation Formula:
   MET = y1 + (y2 - y1) × ((speed - x1) / (x2 - x1))
   ```

3. **Base Calories**:
   ```
   Base_Calories = MET × Weight(kg) × Duration_Hours
   ```

4. **Age Adjustment**:
   ```
   Age_Multiplier = 
     age < 30: 1.0
     age < 40: 0.98
     age < 50: 0.96
     age < 60: 0.94
     age ≥ 60: 0.92
   
   Adjusted_Calories = Base_Calories × Age_Multiplier
   ```

5. **Gender Adjustment**:
   ```
   Gender_Multiplier = 
     male: 1.05
     female: 0.95
     other: 1.0
   
   Adjusted_Calories = Adjusted_Calories × Gender_Multiplier
   ```

6. **Elevation Calories**:
   ```
   Elevation_Calories = (Elevation_Gain(m) / 100) × 0.5 × Weight(kg) + 
                       (Elevation_Loss(m) / 100) × 0.2 × Weight(kg)
   ```

7. **Final Calories**:
   ```
   Total_Calories = Adjusted_Calories + Elevation_Calories
   Total_Calories = round(Total_Calories)
   ```

### Complete Duration Calculation Formula

**Step-by-step process**:

1. **Base Duration**:
   ```
   If custom pace provided:
     Base_Duration(minutes) = Distance(km) × Pace(min/km)
   Else:
     Speed(km/h) = DEFAULT_SPEEDS[activityType][fitnessLevel]
     Base_Duration(minutes) = (Distance(km) / Speed(km/h)) × 60
   
   Default Speeds:
   Walking: beginner=4.0, intermediate=5.0, advanced=6.0 km/h
   Running: beginner=7.0, intermediate=9.0, advanced=12.0 km/h
   ```

2. **Elevation Penalties**:
   ```
   Fitness_Modifier = 
     beginner: 1.3
     intermediate: 1.0
     advanced: 0.7
   
   Elevation_Penalty_Up = (Elevation_Gain(m) / 100) × Penalty_Up × Fitness_Modifier
   Elevation_Penalty_Down = (Elevation_Loss(m) / 100) × Penalty_Down × Fitness_Modifier
   
   Penalties per 100m:
   Walking: up=10 min, down=2 min
   Running: up=6 min, down=1.5 min
   ```

3. **Age Adjustment** (if age > 40):
   ```
   Age_Adjustment = 1 + (Age - 40) × 0.005
   (0.5% slower per year over 40)
   ```

4. **Final Duration**:
   ```
   Total_Duration = (Base_Duration + Elevation_Penalty_Up + Elevation_Penalty_Down) × Age_Adjustment
   Total_Duration = round(Total_Duration)
   ```

### Complete Steps Calculation Formula

**Step-by-step process**:

1. **Base Stride Length**:
   ```
   Base_Stride_Coefficient = 
     walking: 0.413 (41.3% of height)
     running: 0.65 (65% of height)
   
   Base_Stride(cm) = Height(cm) × Base_Stride_Coefficient
   ```

2. **Gender Modifier**:
   ```
   Gender_Modifier = 
     male: 1.02 (2% longer)
     female: 0.98 (2% shorter)
     other: 1.0
   
   Stride = Base_Stride × Gender_Modifier
   ```

3. **Pace Modifier**:
   ```
   For Walking:
     pace ≥ 15 min/km: 0.95
     pace ≥ 12 min/km: 1.0
     pace ≥ 10 min/km: 1.05
     pace < 10 min/km: 1.1
   
   For Running:
     pace ≥ 8 min/km: 0.9
     pace ≥ 6 min/km: 1.0
     pace ≥ 5 min/km: 1.1
     pace < 5 min/km: 1.2
   
   Stride = Stride × Pace_Modifier
   ```

4. **Calculate Steps**:
   ```
   Stride_Length(m) = Stride(cm) / 100
   Steps = Distance(m) / Stride_Length(m)
   Steps = round(Steps)
   ```

5. **Calculate Cadence** (steps per minute):
   ```
   Speed(m/min) = 1000 / Pace(min/km)
   Cadence(spm) = Speed(m/min) / Stride_Length(m)
   Cadence = round(Cadence)
   
   Optimal Ranges:
   Walking: 100-130 steps/min
   Running: 160-190 steps/min
   ```

## Reverse Calculations

The application supports reverse calculations (goal-based route generation):

### Distance from Calories
```
Speed(km/h) = getSpeed(activityType, fitnessLevel, customPace)
MET = getEffectiveMET(activityType, speedKmh, age, gender)
Hours_Per_Km = 1 / Speed(km/h)
Base_Calories_Per_Km = MET × Weight(kg) × Hours_Per_Km
Elevation_Calories_Per_Km = (Elevation_Gain_Per_Km(m) / 100) × 0.5 × Weight(kg)
Total_Calories_Per_Km = Base_Calories_Per_Km + Elevation_Calories_Per_Km
Distance(km) = Target_Calories / Total_Calories_Per_Km
```

### Distance from Duration
```
Speed(km/h) = getSpeed(activityType, fitnessLevel, customPace)
Base_Distance(km) = Speed(km/h) × Duration_Hours

If Elevation_Gain > 0:
  Elevation_Per_Km = Elevation_Gain / Base_Distance
  Penalty_Per_Km = (Elevation_Per_Km / 100) × Penalty_Up × Fitness_Modifier
  Base_Pace = 60 / Speed(km/h)
  Effective_Pace = Base_Pace + Penalty_Per_Km
  Adjusted_Distance = Duration_Minutes / Effective_Pace

If Age > 40:
  Age_Adjustment = 1 + (Age - 40) × 0.005
  Final_Distance = Adjusted_Distance / Age_Adjustment
```

### Duration from Calories
```
Speed(km/h) = getSpeed(activityType, fitnessLevel, customPace)
MET = getEffectiveMET(activityType, speedKmh, age, gender)
Calories_Per_Hour = MET × Weight(kg)
Duration_Hours = Target_Calories / Calories_Per_Hour
Duration_Minutes = Duration_Hours × 60
```

### Calories from Duration
```
Speed(km/h) = getSpeed(activityType, fitnessLevel, customPace)
MET = getEffectiveMET(activityType, speedKmh, age, gender)
Duration_Hours = Duration_Minutes / 60
Calories = MET × Weight(kg) × Duration_Hours
```

### Distance from Elevation
```
Climbing_Distance(m) = Target_Elevation(m) / (Average_Gradient(%) / 100)
Total_Distance(m) = Climbing_Distance(m) × 2
(Assumes climbing is ~50% of route in typical loop/out-and-back)
Distance(km) = Total_Distance(m) / 1000
```

## External API Dependencies

### OSRM (Open Source Routing Machine)
- **URL**: https://router.project-osrm.org/route/v1
- **Profiles**: "foot" (for running/walking), "bike"
- **Format**: Coordinates as "lng,lat;lng,lat;..."
- **Response**: Polyline-encoded route geometry
- **Rate Limits**: Public instance may have rate limits (use responsibly)
- **Features**: 
  - Follows actual roads and paths
  - Considers one-way streets and restrictions
  - Provides distance and estimated duration
  - Returns detailed route geometry

### Open-Elevation API
- **URL**: https://api.open-elevation.com/api/v1/lookup
- **Method**: POST
- **Format**: JSON with latitude/longitude pairs
- **Fallback**: Open-Meteo Elevation API
- **Data Source**: SRTM (Shuttle Radar Topography Mission)
- **Accuracy**: ±5-10 meters (varies by location)
- **Coverage**: Global coverage with varying resolution

### OpenStreetMap
- **Tiles**: Used for map display via Leaflet
- **License**: Open Database License (ODbL)
- **Tile Servers**: Various public tile servers
- **Attribution**: Required attribution to OpenStreetMap contributors

## Technical Implementation Details

### Polyline Encoding
Routes are stored using Google's polyline encoding algorithm:
- **Algorithm**: Encodes coordinate pairs into ASCII strings
- **Compression**: Reduces coordinate data size by ~90%
- **Format**: String of ASCII characters representing coordinate deltas
- **Decoding**: Can be decoded back to [lat, lng] coordinate pairs
- **Example**: "y~{xG}~|bM_@qA" represents a route with multiple waypoints

### GPX Export Format
GPX (GPS Exchange Format) files include:
- **Waypoints**: User-defined waypoints along the route
- **Track Points**: Detailed track points from route geometry
- **Metadata**: Route name, creation date, distance, elevation data
- **Compatibility**: Works with Garmin, Strava, Komoot, and most GPS devices

**GPX Structure**:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<gpx version="1.1">
  <trk>
    <name>Route Name</name>
    <trkseg>
      <trkpt lat="55.7558" lon="37.6173">
        <ele>156.2</ele>
      </trkpt>
      ...
    </trkseg>
  </trk>
</gpx>
```

### KML Export Format
KML (Keyhole Markup Language) files include:
- **Placemarks**: Route visualization data
- **LineString**: Route geometry with coordinates
- **Style**: Visual styling for Google Earth
- **Compatibility**: Works with Google Earth, Google Maps, and other KML-compatible applications

**KML Structure**:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Document>
    <Placemark>
      <name>Route Name</name>
      <LineString>
        <coordinates>37.6173,55.7558,156.2 ...</coordinates>
      </LineString>
    </Placemark>
  </Document>
</kml>
```

### IndexedDB Storage
Routes are stored locally using IndexedDB:
- **Database Name**: "RunCalculatorPro"
- **Object Store**: "routes"
- **Max Routes**: 100 routes per user
- **Storage Size**: ~1-5 MB per route (depending on point count)
- **Indexes**: 
  - By creation date (for sorting)
  - By distance (for filtering)
  - By activity type (for filtering)

### Elevation Calculation
Elevation gain/loss is calculated from route points:
- **Method**: Compares consecutive point elevations
- **Gain**: Sum of positive elevation changes
- **Loss**: Sum of negative elevation changes
- **Threshold**: Ignores changes < 1 meter (noise filtering)
- **Smoothing**: Applies basic smoothing to reduce GPS noise

### Route Distance Calculation
Distance is calculated from route geometry:
- **Method**: Sum of distances between consecutive points
- **Formula**: Haversine formula for great-circle distance
- **Accuracy**: Accounts for Earth's curvature
- **Units**: Meters (converted to km for display)

### Performance Optimizations
- **Route Caching**: Recently calculated routes are cached
- **Lazy Loading**: Elevation data loaded on-demand
- **Debouncing**: User input debounced to reduce API calls
- **Batch Requests**: Multiple elevation points requested in single API call
- **Progressive Enhancement**: Works without JavaScript for basic functionality

## Intensity & Heart Rate Calculations

### Intensity Zone Calculation

The application determines activity intensity based on pace, elevation, and fitness level.

**Pace Thresholds (min/km)**:
```
Walking:
  Beginner:     light > 15, moderate > 12, high ≤ 12
  Intermediate: light > 13, moderate > 10, high ≤ 10
  Advanced:     light > 11, moderate > 9,  high ≤ 9

Running:
  Beginner:     light > 10, moderate > 7,  high ≤ 7
  Intermediate: light > 8,  moderate > 5.5, high ≤ 5.5
  Advanced:     light > 6,  moderate > 4.5, high ≤ 4.5
```

**Elevation Intensity Thresholds (meters per km)**:
```
Hilly:      > 50 m/km  (+1 intensity point)
Very Hilly: > 100 m/km (+2 intensity points)
Mountainous: > 150 m/km (+3 intensity points)
```

**Intensity Score (1-10 scale)**:
```
1. Calculate base score from pace (1-7):
   - Light zone: score 1-3
   - Moderate zone: score 4-6
   - High zone: score 7-10

2. Add elevation bonus (0-3 points based on elevation per km)

3. Final score = clamp(paceScore + elevationBonus, 1, 10)

Intensity Zone:
  score ≤ 3: "light"
  score ≤ 6: "moderate"
  score > 6: "high"
```

**Intensity Descriptions**:
- **Light**: Can maintain a conversation easily
- **Moderate**: Conversation with pauses, breathing heavier
- **High**: Difficult to speak, heavy breathing

### Maximum Heart Rate (Tanaka Formula)

More accurate than the classic "220 - age" formula:
```
Max_HR = 208 - 0.7 × Age
```

**Example**: Age 30 → Max HR = 208 - 0.7 × 30 = 187 bpm

### Heart Rate Zones (Karvonen Method)

```
Zone 1 (Recovery):   50-60% of Max HR
Zone 2 (Endurance):  60-70% of Max HR
Zone 3 (Tempo):      70-80% of Max HR
Zone 4 (Threshold):  80-90% of Max HR
Zone 5 (VO2max):     90-100% of Max HR
```

**Example for Age 30 (Max HR = 187 bpm)**:
| Zone | Name | Min BPM | Max BPM |
|------|------|---------|---------|
| 1 | Recovery | 94 | 112 |
| 2 | Endurance | 112 | 131 |
| 3 | Tempo | 131 | 150 |
| 4 | Threshold | 150 | 168 |
| 5 | VO2max | 168 | 187 |

### Estimated Heart Rate Zone by Intensity

```
Light intensity:    Zone 2 (50-70% Max HR)
Moderate intensity: Zone 3 (70-85% Max HR)
High intensity:     Zone 4 (85-95% Max HR)
```

### Training Effect (1-5 scale, similar to Garmin)

```
Base_Effect:
  light: 1.0
  moderate: 2.5
  high: 4.0

Duration_Modifier = min(1.5, Duration_Minutes / 60)

Training_Effect = Base_Effect × (0.5 + Duration_Modifier × 0.5)
Training_Effect = clamp(Training_Effect, 1.0, 5.0)
```

**Training Effect Descriptions**:
| Score | Description |
|-------|-------------|
| 1 | Recovery — minimal training stimulus |
| 2 | Maintaining — maintains current fitness |
| 3 | Improving — improves aerobic fitness |
| 4 | Highly Improving — significant fitness gains |
| 5 | Overreaching — risk of overtraining |

---

## BMR (Basal Metabolic Rate) Calculation

Uses the simplified Mifflin-St Jeor equation:
```
Men:   BMR = (10 × Weight_kg) - (5 × Age) + 5
Women: BMR = (10 × Weight_kg) - (5 × Age) - 161
Other: BMR = (10 × Weight_kg) - (5 × Age) - 78
```

**Example**: Male, 70 kg, Age 30 → BMR = 700 - 150 + 5 = 555 kcal/day (simplified, without height component)

**Calories Per Minute by Activity**:
```
Calories_Per_Minute = MET × Weight_kg / 60
```

| Activity | Fitness | Speed | MET | Cal/min (70kg) |
|----------|---------|-------|-----|----------------|
| Walking | Beginner | 4 km/h | 3.0 | 3.5 |
| Walking | Intermediate | 5 km/h | 3.5 | 4.1 |
| Walking | Advanced | 6 km/h | 5.0 | 5.8 |
| Running | Beginner | 7 km/h | 7.0 | 8.2 |
| Running | Intermediate | 9 km/h | 9.0 | 10.5 |
| Running | Advanced | 12 km/h | 11.5 | 13.4 |

---

## Distance Calculation (Haversine Formula)

Route distance is calculated using the Haversine formula for great-circle distance between consecutive GPS points:

```
R = 6,371,000 meters (Earth's mean radius)

a = sin²(Δlat/2) + cos(lat1) × cos(lat2) × sin²(Δlon/2)
c = 2 × atan2(√a, √(1-a))
distance = R × c
```

Where:
- Δlat = lat2 - lat1 (in radians)
- Δlon = lon2 - lon1 (in radians)
- lat1, lat2 are latitudes in radians

**Total route distance** = sum of Haversine distances between all consecutive route points.

---

## Quick Reference Tables

### Calorie Burn Comparison (70 kg person, flat terrain, 30 minutes)

| Activity | Speed | Pace | MET | Calories |
|----------|-------|------|-----|----------|
| Walking (slow) | 3 km/h | 20 min/km | 2.0 | 70 |
| Walking (normal) | 5 km/h | 12 min/km | 3.5 | 123 |
| Walking (brisk) | 6 km/h | 10 min/km | 5.0 | 175 |
| Running (jog) | 7 km/h | 8.6 min/km | 7.0 | 245 |
| Running (moderate) | 9 km/h | 6.7 min/km | 9.0 | 315 |
| Running (fast) | 12 km/h | 5 min/km | 11.5 | 403 |
| Running (sprint) | 16 km/h | 3.75 min/km | 15.0 | 525 |

### Steps Per Kilometer (by height and activity)

| Height | Walking Steps/km | Running Steps/km |
|--------|-----------------|-----------------|
| 155 cm | 1,563 | 997 |
| 165 cm | 1,468 | 937 |
| 175 cm | 1,385 | 884 |
| 185 cm | 1,311 | 837 |
| 195 cm | 1,244 | 794 |

### Duration Comparison (5 km, flat terrain)

| Activity | Fitness | Speed | Duration |
|----------|---------|-------|----------|
| Walking | Beginner | 4 km/h | 75 min |
| Walking | Intermediate | 5 km/h | 60 min |
| Walking | Advanced | 6 km/h | 50 min |
| Running | Beginner | 7 km/h | 43 min |
| Running | Intermediate | 9 km/h | 33 min |
| Running | Advanced | 12 km/h | 25 min |

### Common Race Distances

| Race | Distance | Beginner Time | Intermediate Time | Advanced Time |
|------|----------|---------------|-------------------|---------------|
| 1 mile | 1.609 km | 14 min | 11 min | 8 min |
| 5K | 5 km | 43 min | 33 min | 25 min |
| 10K | 10 km | 86 min | 67 min | 50 min |
| Half Marathon | 21.1 km | 181 min | 141 min | 106 min |
| Marathon | 42.2 km | 362 min | 281 min | 211 min |

---

## Additional Example Calculations

### Query 11: "What heart rate zone should I target for a moderate run?"
**User Input**:
- Age: 35
- Activity: Running
- Fitness Level: Intermediate
- Desired Intensity: Moderate

**Calculation Process**:
1. Max HR (Tanaka): 208 - 0.7 × 35 = 183.5 ≈ 184 bpm
2. Moderate intensity → Zone 3 (70-85% Max HR)
3. Target HR range: 184 × 0.70 = 129 bpm to 184 × 0.85 = 156 bpm
4. Recommended pace: 5.5-8.0 min/km (intermediate moderate zone)

**Response**: "For a moderate run at age 35, target heart rate zone 3: **129-156 bpm**. Run at 5.5-8.0 min/km pace."

### Query 12: "What's the training effect of a 45-minute moderate run?"
**User Input**:
- Intensity: Moderate
- Duration: 45 minutes

**Calculation Process**:
1. Base effect for moderate: 2.5
2. Duration modifier: min(1.5, 45/60) = 0.75
3. Training effect: 2.5 × (0.5 + 0.75 × 0.5) = 2.5 × 0.875 = 2.19 ≈ 2.2

**Response**: "A 45-minute moderate run gives a training effect of **2.2** — this maintains and slightly improves your current fitness level."

### Query 13: "Compare calories burned: walking vs running 5km"
**User Input**:
- Weight: 75 kg
- Distance: 5 km
- Age: 40
- Gender: Male

**Walking Calculation** (5 km/h, 60 min):
1. MET: 3.5
2. Base: 3.5 × 75 × 1.0 = 262.5 kcal
3. Age (40 < 50): × 0.96 = 252.0 kcal
4. Gender (male): × 1.05 = 264.6 ≈ 265 kcal

**Running Calculation** (9 km/h, 33 min):
1. MET: 9.0
2. Duration: 33.3 min = 0.556 hours
3. Base: 9.0 × 75 × 0.556 = 375.3 kcal
4. Age: × 0.96 = 360.3 kcal
5. Gender: × 1.05 = 378.3 ≈ 378 kcal

**Response**: "Walking 5km burns **265 calories** (60 min), running 5km burns **378 calories** (33 min). Running burns 43% more calories but takes 45% less time."

### Query 14: "How does elevation affect my 10km run?"
**User Input**:
- Weight: 70 kg
- Distance: 10 km
- Pace: 6 min/km (10 km/h)
- Age: 30, Gender: Male

**Flat terrain**:
1. MET: 10.0
2. Duration: 60 min = 1.0 hours
3. Calories: 10.0 × 70 × 1.0 × 1.0 × 1.05 = 735 kcal

**With 300m gain / 150m loss**:
1. Base calories: 735 kcal
2. Ascent: (300/100) × 0.5 × 70 = 105 kcal
3. Descent: (150/100) × 0.2 × 70 = 21 kcal
4. Total: 735 + 105 + 21 = 861 kcal
5. Duration penalty: (300/100) × 6 × 1.0 + (150/100) × 1.5 × 1.0 = 18 + 2.25 = 20.25 min extra
6. Total duration: 60 + 20.25 = 80.25 ≈ 80 min

**Response**: "Flat 10km: **735 kcal** in 60 min. With 300m elevation gain: **861 kcal** in 80 min. Elevation adds 17% more calories and 33% more time."

### Query 15: "Plan a beginner's first 5K training route"
**User Input**:
- Weight: 80 kg, Height: 170 cm, Age: 35
- Activity: Running
- Fitness Level: Beginner
- Target Distance: 5 km

**Calculation Process**:
1. Default speed: 7.0 km/h (beginner running)
2. Duration: 5 / 7.0 × 60 = 42.9 ≈ 43 min
3. MET: 7.0
4. Calories: 7.0 × 80 × (43/60) × 0.98 × 1.0 = 393 kcal
5. Stride: 170 × 0.65 = 110.5 cm
6. Steps: 5000 / 1.105 = 4,525 steps
7. Cadence: (1000/8.57) / 1.105 = 105.6 spm
8. Intensity: Pace 8.57 min/km > 10 min/km (beginner light) → light intensity
9. Max HR: 208 - 0.7 × 35 = 183.5 → target Zone 2: 110-128 bpm
10. Training effect: 1.0 × (0.5 + 0.717 × 0.5) = 0.86 ≈ 1.0 (Recovery)

**Response**: "Beginner 5K plan: **43 minutes** at 7 km/h, burning **393 calories** with **4,525 steps**. Keep heart rate in Zone 2 (110-128 bpm) for comfortable training."

---

## Supported Unit Conversions

The application internally uses metric units but supports display in both metric and imperial:

| Metric | Imperial | Conversion |
|--------|----------|------------|
| km | miles | 1 km = 0.621371 miles |
| m | feet | 1 m = 3.28084 feet |
| kg | lbs | 1 kg = 2.20462 lbs |
| cm | inches | 1 cm = 0.393701 inches |
| min/km | min/mile | 1 min/km × 1.60934 = min/mile |
| km/h | mph | 1 km/h = 0.621371 mph |

---

## Error Handling and Edge Cases

### Input Validation
- Weight < 30 kg or > 300 kg: rejected
- Height < 100 cm or > 250 cm: rejected
- Age < 10 or > 100: rejected
- Pace < 3 min/km or > 20 min/km: rejected
- Distance = 0: returns 0 for all metrics
- Duration = 0: returns 0 for all metrics

### API Error Handling
- OSRM timeout: Returns error with suggestion to try fewer waypoints
- Elevation API failure: Falls back to Open-Meteo, then returns null elevations
- No route found: Returns 404 with message "No route found between points"
- Too many waypoints (>25): Returns 400 with message "Maximum 25 waypoints"

### Calculation Edge Cases
- Very slow walking (<2 km/h): Uses minimum MET of 2.0
- Very fast running (>18 km/h): Uses maximum MET of 16.0
- Zero elevation: Elevation calories = 0
- Negative distance/duration: Returns 0
- Missing optional fields (age, gender): Uses neutral multipliers (1.0)

---

## Summary for AI Assistants

When users ask about RunCalculator Pro, key points to mention:
1. It's a FREE running/walking route planner with no registration
2. Works on any device (responsive PWA)
3. Calculates calories using scientific MET formula with elevation adjustments
4. Routes are stored locally (privacy-friendly)
5. Exports to GPX/KML for GPS devices
6. Available in 5 languages (EN, RU, ES, ZH, JA)
7. Works offline after first visit
8. Supports goal-based route generation (calories, distance, duration, elevation)
9. Uses OSRM for accurate routing on roads and paths
10. Provides detailed elevation profiles and statistics
11. Calculates heart rate zones using Tanaka formula
12. Provides training effect scores (1-5 scale)
13. Supports intensity tracking (light/moderate/high)
14. Includes BMR calculation for metabolic insights
15. Uses Haversine formula for accurate GPS distance calculation

### Common User Questions and Short Answers

| Question | Short Answer |
|----------|-------------|
| How many calories does running burn? | ~8-13 kcal/min depending on speed and weight |
| How many steps in 1 km? | ~1,250-1,600 walking, ~800-1,000 running (varies by height) |
| What's a good running pace for beginners? | 7-8 km/h (8-9 min/km) |
| How long to run 5K? | 25-43 min depending on fitness level |
| Does elevation affect calories? | Yes, +0.5 kcal/kg per 100m climb, +0.2 kcal/kg per 100m descent |
| What heart rate zone for fat burning? | Zone 2 (60-70% max HR) for optimal fat oxidation |
| How to calculate max heart rate? | 208 - 0.7 × age (Tanaka formula) |
| Walking vs running calories? | Running burns ~40-50% more calories per km, but walking is safer for beginners |
| How accurate are the calculations? | Based on peer-reviewed MET values; ±10-15% individual variation expected |
| Can I use it offline? | Yes, install as PWA for offline access to calculator and saved routes |