Running Days Docs
GitHub

Goals API

Manage yearly running goals and track progress.

Overview

Goals represent yearly targets for running days. The default goal is 300 days per year, but users can customize this from 1-366 days.

Endpoints

List Goals

http 
GET /api/v1/goals

Returns all goals with basic progress information.

Response:

json 
{
  "goals": [
    {
      "year": 2024,
      "targetDays": 300,
      "completedDays": 150,
      "percentComplete": 50
    }
  ]
}

Create Goal

http 
POST /api/v1/goals

Creates a new yearly goal.

Request Body:

json 
{
  "year": 2024,
  "targetDays": 300
}

Response:

json 
{
  "year": 2024,
  "targetDays": 300,
  "completedDays": 0,
  "percentComplete": 0
}

Get Goal

http 
GET /api/v1/goals/:year

Returns a specific year’s goal with basic progress.

Response:

json 
{
  "year": 2024,
  "targetDays": 300,
  "completedDays": 150,
  "percentComplete": 50
}

Update Goal

http 
PUT /api/v1/goals/:year

Updates the target days for a goal.

Request Body:

json 
{
  "targetDays": 250
}

Delete Goal

http 
DELETE /api/v1/goals/:year

Deletes a goal (does not delete associated workouts).

Get Detailed Progress

http 
GET /api/v1/goals/:year/progress

Returns comprehensive progress data including streaks and achievements.

Response:

json 
{
  "year": 2024,
  "targetDays": 300,
  "completedDays": 150,
  "percentComplete": 50,
  "daysRemaining": 150,
  "daysLeftInYear": 200,
  "requiredPace": 0.75,
  "actualPace": 0.82,
  "onTrack": true,
  "streak": {
    "current": 5,
    "longest": 21,
    "history": [
      { "start": "2024-01-10", "end": "2024-01-30", "length": 21 }
    ]
  },
  "achievements": [
    { "milestone": 50, "unlockedAt": "2024-02-15T00:00:00Z" },
    { "milestone": 100, "unlockedAt": "2024-04-20T00:00:00Z" }
  ],
  "monthlyBreakdown": [
    { "month": 1, "days": 20 },
    { "month": 2, "days": 18 }
  ]
}

Business Logic

Pace Calculation

  • Required Pace: remainingDays / daysLeftInYear
  • Actual Pace: completedDays / daysSoFar
  • On Track: actualPace >= requiredPace

Streak Rules

  • A streak is consecutive days with at least one run
  • Multiple runs on the same day count as one day
  • Streaks reset when a day is missed