API Reference

Activity summaries sub-module for aggregated metrics.

This module provides summary aggregations of activity data across different time periods (weekly, monthly, yearly, lifetime) with breakdowns by day, week, month, year, and activity type.

Exports

• CRUD: get_weekly_summary, get_monthly_summary, get_yearly_summary, get_lifetime_summary
• Schemas: SummaryMetrics, DaySummary, WeekSummary, MonthSummary, YearlyPeriodSummary, TypeBreakdownItem, WeeklySummaryResponse, MonthlySummaryResponse, YearlySummaryResponse, LifetimeSummaryResponse
• Dependencies: validate_view_type

DaySummary

Bases: SummaryMetrics

Daily activity summary within a week.

Attributes:

Name	Type	Description
day_of_week	StrictInt	Day of week (0=Mon, 6=Sun).

Source code in backend/app/activities/activity_summaries/schema.py

class DaySummary(SummaryMetrics):
    """
    Daily activity summary within a week.

    Attributes:
        day_of_week: Day of week (0=Mon, 6=Sun).
    """

    day_of_week: StrictInt = Field(
        ...,
        description=(
            "Day of week (0=Monday, 6=Sunday)"
        ),
    )

LifetimeSummaryResponse

Bases: SummaryMetrics

Lifetime summary with yearly breakdowns.

Attributes:

Name	Type	Description
breakdown	list[YearlyPeriodSummary]	List of yearly summaries.
type_breakdown	list[TypeBreakdownItem] | None	Optional breakdown by type.

Source code in backend/app/activities/activity_summaries/schema.py

class LifetimeSummaryResponse(SummaryMetrics):
    """
    Lifetime summary with yearly breakdowns.

    Attributes:
        breakdown: List of yearly summaries.
        type_breakdown: Optional breakdown by type.
    """

    breakdown: list[YearlyPeriodSummary] = Field(
        ...,
        description="List of yearly summaries",
    )
    type_breakdown: (
        list[TypeBreakdownItem] | None
    ) = Field(
        default=None,
        description=(
            "Optional breakdown by activity type"
        ),
    )

MonthSummary

Bases: SummaryMetrics

Monthly activity summary within a year.

Attributes:

Name	Type	Description
month_number	StrictInt	Month (1=Jan, 12=Dec).

Source code in backend/app/activities/activity_summaries/schema.py

class MonthSummary(SummaryMetrics):
    """
    Monthly activity summary within a year.

    Attributes:
        month_number: Month (1=Jan, 12=Dec).
    """

    month_number: StrictInt = Field(
        ...,
        description="Month (1=January, 12=December)",
    )

MonthlySummaryResponse

Bases: SummaryMetrics

Monthly summary with weekly breakdowns.

Attributes:

Name	Type	Description
breakdown	list[WeekSummary]	List of weekly summaries.
type_breakdown	list[TypeBreakdownItem] | None	Optional breakdown by type.

Source code in backend/app/activities/activity_summaries/schema.py

class MonthlySummaryResponse(SummaryMetrics):
    """
    Monthly summary with weekly breakdowns.

    Attributes:
        breakdown: List of weekly summaries.
        type_breakdown: Optional breakdown by type.
    """

    breakdown: list[WeekSummary] = Field(
        ...,
        description="List of weekly summaries",
    )
    type_breakdown: (
        list[TypeBreakdownItem] | None
    ) = Field(
        default=None,
        description=(
            "Optional breakdown by activity type"
        ),
    )

SummaryMetrics

Bases: BaseModel

Base metrics shared by all summary responses.

Attributes:

Name	Type	Description
total_distance	StrictFloat	Total distance in meters.
total_duration	StrictFloat	Total duration in seconds.
total_elevation_gain	StrictFloat	Total elevation gain in meters.
activity_count	StrictInt	Number of activities.
total_calories	StrictFloat	Total calories burned.

Source code in backend/app/activities/activity_summaries/schema.py

class SummaryMetrics(BaseModel):
    """
    Base metrics shared by all summary responses.

    Attributes:
        total_distance: Total distance in meters.
        total_duration: Total duration in seconds.
        total_elevation_gain: Total elevation gain
            in meters.
        activity_count: Number of activities.
        total_calories: Total calories burned.
    """

    total_distance: StrictFloat = Field(
        default=0.0,
        description="Total distance in meters",
    )
    total_duration: StrictFloat = Field(
        default=0.0,
        description="Total duration in seconds",
    )
    total_elevation_gain: StrictFloat = Field(
        default=0.0,
        description="Total elevation gain in meters",
    )
    activity_count: StrictInt = Field(
        default=0,
        description="Number of activities",
    )
    total_calories: StrictFloat = Field(
        default=0.0,
        description="Total calories burned",
    )

    model_config = ConfigDict(
        from_attributes=True,
        extra="forbid",
        validate_assignment=True,
    )

TypeBreakdownItem

Bases: SummaryMetrics

Summary metrics broken down by activity type.

Attributes:

Name	Type	Description
activity_type_id	StrictInt	Numeric activity type ID.
activity_type	StrictStr	Human-readable type name.

Source code in backend/app/activities/activity_summaries/schema.py

class TypeBreakdownItem(SummaryMetrics):
    """
    Summary metrics broken down by activity type.

    Attributes:
        activity_type_id: Numeric activity type ID.
        activity_type: Human-readable type name.
    """

    activity_type_id: StrictInt = Field(
        ...,
        description="Numeric activity type ID",
    )
    activity_type: StrictStr = Field(
        ...,
        description=(
            "Human-readable activity type name"
        ),
    )

WeekSummary

Bases: SummaryMetrics

Weekly activity summary within a month.

Attributes:

Name	Type	Description
week_number	StrictInt	ISO week number.

Source code in backend/app/activities/activity_summaries/schema.py

class WeekSummary(SummaryMetrics):
    """
    Weekly activity summary within a month.

    Attributes:
        week_number: ISO week number.
    """

    week_number: StrictInt = Field(
        ...,
        description="ISO week number",
    )

WeeklySummaryResponse

Bases: SummaryMetrics

Weekly summary with daily breakdowns.

Attributes:

Name	Type	Description
breakdown	list[DaySummary]	List of daily summaries.
type_breakdown	list[TypeBreakdownItem] | None	Optional breakdown by type.

Source code in backend/app/activities/activity_summaries/schema.py

class WeeklySummaryResponse(SummaryMetrics):
    """
    Weekly summary with daily breakdowns.

    Attributes:
        breakdown: List of daily summaries.
        type_breakdown: Optional breakdown by type.
    """

    breakdown: list[DaySummary] = Field(
        ...,
        description="List of daily summaries",
    )
    type_breakdown: (
        list[TypeBreakdownItem] | None
    ) = Field(
        default=None,
        description=(
            "Optional breakdown by activity type"
        ),
    )

YearlyPeriodSummary

Bases: SummaryMetrics

Yearly activity summary within lifetime view.

Attributes:

Name	Type	Description
year_number	StrictInt	Calendar year.

Source code in backend/app/activities/activity_summaries/schema.py

class YearlyPeriodSummary(SummaryMetrics):
    """
    Yearly activity summary within lifetime view.

    Attributes:
        year_number: Calendar year.
    """

    year_number: StrictInt = Field(
        ...,
        description="Calendar year",
    )

YearlySummaryResponse

Bases: SummaryMetrics

Yearly summary with monthly breakdowns.

Attributes:

Name	Type	Description
breakdown	list[MonthSummary]	List of monthly summaries.
type_breakdown	list[TypeBreakdownItem] | None	Optional breakdown by type.

Source code in backend/app/activities/activity_summaries/schema.py

class YearlySummaryResponse(SummaryMetrics):
    """
    Yearly summary with monthly breakdowns.

    Attributes:
        breakdown: List of monthly summaries.
        type_breakdown: Optional breakdown by type.
    """

    breakdown: list[MonthSummary] = Field(
        ...,
        description="List of monthly summaries",
    )
    type_breakdown: (
        list[TypeBreakdownItem] | None
    ) = Field(
        default=None,
        description=(
            "Optional breakdown by activity type"
        ),
    )

get_lifetime_summary

get_lifetime_summary(db, user_id, activity_type=None)

Get lifetime activity summary for a user.

Parameters:

Name	Type	Description	Default
db	Session	Database session.	required
user_id	int	Target user ID.	required
activity_type	str | None	Optional activity type filter name.	None

Returns:

Type	Description
LifetimeSummaryResponse	Lifetime summary with yearly breakdowns.

Source code in backend/app/activities/activity_summaries/crud.py

def get_lifetime_summary(
    db: Session,
    user_id: int,
    activity_type: str | None = None,
) -> LifetimeSummaryResponse:
    """
    Get lifetime activity summary for a user.

    Args:
        db: Database session.
        user_id: Target user ID.
        activity_type: Optional activity type
            filter name.

    Returns:
        Lifetime summary with yearly breakdowns.
    """
    # Overall metrics
    metrics_stmt = select(
        func.coalesce(
            func.sum(Activity.distance), 0.0
        ).label("total_distance"),
        func.coalesce(
            func.sum(Activity.total_timer_time),
            0.0,
        ).label("total_duration"),
        func.coalesce(
            func.sum(Activity.elevation_gain),
            0.0,
        ).label("total_elevation_gain"),
        func.coalesce(
            func.sum(Activity.calories), 0.0
        ).label("total_calories"),
        func.count(Activity.id).label(
            "activity_count"
        ),
    ).where(Activity.user_id == user_id)

    metrics_stmt, type_id = (
        _apply_activity_type_filter(
            metrics_stmt, activity_type
        )
    )

    totals = db.execute(
        metrics_stmt
    ).one_or_none()

    # Yearly breakdown
    year_expr = extract(
        "year", Activity.start_time
    )
    yearly_stmt = select(
        year_expr.label("year_number"),
        func.coalesce(
            func.sum(Activity.distance), 0.0
        ).label("total_distance"),
        func.coalesce(
            func.sum(Activity.total_timer_time),
            0.0,
        ).label("total_duration"),
        func.coalesce(
            func.sum(Activity.elevation_gain),
            0.0,
        ).label("total_elevation_gain"),
        func.coalesce(
            func.sum(Activity.calories), 0.0
        ).label("total_calories"),
        func.count(Activity.id).label(
            "activity_count"
        ),
    ).where(Activity.user_id == user_id)

    yearly_stmt, _ = _apply_activity_type_filter(
        yearly_stmt, activity_type
    )

    yearly_stmt = yearly_stmt.group_by(
        year_expr
    ).order_by(year_expr.desc())

    yearly_rows = db.execute(yearly_stmt).all()
    breakdown: list[YearlyPeriodSummary] = []
    for row in yearly_rows:
        breakdown.append(
            YearlyPeriodSummary(
                year_number=int(row.year_number),
                total_distance=float(
                    row.total_distance
                ),
                total_duration=float(
                    row.total_duration
                ),
                total_elevation_gain=float(
                    row.total_elevation_gain
                ),
                total_calories=float(
                    row.total_calories
                ),
                activity_count=int(
                    row.activity_count
                ),
            )
        )

    if totals:
        return LifetimeSummaryResponse(
            total_distance=float(
                totals.total_distance
            ),
            total_duration=float(
                totals.total_duration
            ),
            total_elevation_gain=float(
                totals.total_elevation_gain
            ),
            total_calories=float(
                totals.total_calories
            ),
            activity_count=int(
                totals.activity_count
            ),
            breakdown=breakdown,
            type_breakdown=(
                _get_type_breakdown(
                    db,
                    user_id,
                    date.min,
                    date.max,
                    activity_type,
                )
                or []
            ),
        )

    return LifetimeSummaryResponse(
        total_distance=0.0,
        total_duration=0.0,
        total_elevation_gain=0.0,
        total_calories=0.0,
        activity_count=0,
        breakdown=[],
        type_breakdown=[],
    )

get_monthly_summary

get_monthly_summary(db, user_id, target_date, activity_type=None)

Get monthly activity summary for a user.

Parameters:

Name	Type	Description	Default
db	Session	Database session.	required
user_id	int	Target user ID.	required
target_date	date	Any date within the target month.	required
activity_type	str | None	Optional activity type filter name.	None

Returns:

Type	Description
MonthlySummaryResponse	Monthly summary with weekly breakdowns.

Source code in backend/app/activities/activity_summaries/crud.py

def get_monthly_summary(
    db: Session,
    user_id: int,
    target_date: date,
    activity_type: str | None = None,
) -> MonthlySummaryResponse:
    """
    Get monthly activity summary for a user.

    Args:
        db: Database session.
        user_id: Target user ID.
        target_date: Any date within the target
            month.
        activity_type: Optional activity type
            filter name.

    Returns:
        Monthly summary with weekly breakdowns.
    """
    start_of_month = target_date.replace(day=1)
    end_of_month = (
        start_of_month + timedelta(days=32)
    ).replace(day=1)

    week_expr = extract(
        "week", Activity.start_time
    )

    stmt = select(
        week_expr.label("week_number"),
        func.coalesce(
            func.sum(Activity.distance), 0
        ).label("total_distance"),
        func.coalesce(
            func.sum(Activity.total_timer_time),
            0.0,
        ).label("total_duration"),
        func.coalesce(
            func.sum(Activity.elevation_gain), 0
        ).label("total_elevation_gain"),
        func.coalesce(
            func.sum(Activity.calories), 0
        ).label("total_calories"),
        func.count(Activity.id).label(
            "activity_count"
        ),
    ).where(
        Activity.user_id == user_id,
        Activity.start_time >= start_of_month,
        Activity.start_time < end_of_month,
    )

    stmt, _ = _apply_activity_type_filter(
        stmt, activity_type
    )

    stmt = stmt.group_by(week_expr).order_by(
        week_expr
    )

    weekly_results = db.execute(stmt).all()
    breakdown: list[WeekSummary] = []
    overall = SummaryMetrics()

    for week_data in weekly_results:
        ws = WeekSummary(
            week_number=int(
                week_data.week_number
            ),
            total_distance=float(
                week_data.total_distance
            ),
            total_duration=float(
                week_data.total_duration
            ),
            total_elevation_gain=float(
                week_data.total_elevation_gain
            ),
            total_calories=float(
                week_data.total_calories
            ),
            activity_count=int(
                week_data.activity_count
            ),
        )
        breakdown.append(ws)
        overall.total_distance += (
            ws.total_distance
        )
        overall.total_duration += (
            ws.total_duration
        )
        overall.total_elevation_gain += (
            ws.total_elevation_gain
        )
        overall.total_calories += ws.total_calories
        overall.activity_count += ws.activity_count

    return MonthlySummaryResponse(
        total_distance=overall.total_distance,
        total_duration=overall.total_duration,
        total_elevation_gain=(
            overall.total_elevation_gain
        ),
        total_calories=overall.total_calories,
        activity_count=overall.activity_count,
        breakdown=breakdown,
        type_breakdown=_get_type_breakdown(
            db,
            user_id,
            start_of_month,
            end_of_month,
            activity_type,
        ),
    )

get_weekly_summary

get_weekly_summary(db, user_id, target_date, activity_type=None)

Get weekly activity summary for a user.

Parameters:

Name	Type	Description	Default
db	Session	Database session.	required
user_id	int	Target user ID.	required
target_date	date	Any date within the target week.	required
activity_type	str | None	Optional activity type filter name.	None

Returns:

Type	Description
WeeklySummaryResponse	Weekly summary with daily breakdowns.

Source code in backend/app/activities/activity_summaries/crud.py

def get_weekly_summary(
    db: Session,
    user_id: int,
    target_date: date,
    activity_type: str | None = None,
) -> WeeklySummaryResponse:
    """
    Get weekly activity summary for a user.

    Args:
        db: Database session.
        user_id: Target user ID.
        target_date: Any date within the target
            week.
        activity_type: Optional activity type
            filter name.

    Returns:
        Weekly summary with daily breakdowns.
    """
    start_of_week = target_date - timedelta(
        days=target_date.weekday()
    )
    end_of_week = start_of_week + timedelta(days=7)

    # Database-agnostic ISO day of week
    # PostgreSQL: extract('isodow') -> 1-7 Mon-Sun
    # MySQL: DAYOFWEEK (1=Sun, 7=Sat) -> ISO
    engine_name = (
        db.get_bind().dialect.name
    )
    if engine_name == "postgresql":
        iso_dow = extract(
            "isodow", Activity.start_time
        )
    else:
        iso_dow = case(
            (
                func.dayofweek(
                    Activity.start_time
                )
                == 1,
                7,
            ),
            else_=(
                func.dayofweek(
                    Activity.start_time
                )
                - 1
            ),
        )

    stmt = select(
        iso_dow.label("day_of_week"),
        func.coalesce(
            func.sum(Activity.distance), 0
        ).label("total_distance"),
        func.coalesce(
            func.sum(Activity.total_timer_time),
            0.0,
        ).label("total_duration"),
        func.coalesce(
            func.sum(Activity.elevation_gain), 0
        ).label("total_elevation_gain"),
        func.coalesce(
            func.sum(Activity.calories), 0
        ).label("total_calories"),
        func.count(Activity.id).label(
            "activity_count"
        ),
    ).where(
        Activity.user_id == user_id,
        Activity.start_time >= start_of_week,
        Activity.start_time < end_of_week,
    )

    stmt, _ = _apply_activity_type_filter(
        stmt, activity_type
    )

    stmt = stmt.group_by(iso_dow).order_by(
        iso_dow
    )

    daily_results = db.execute(stmt).all()
    breakdown: list[DaySummary] = []
    overall = SummaryMetrics()

    day_map = {
        d.day_of_week: d for d in daily_results
    }

    for i in range(1, 8):
        day_data = day_map.get(i)
        if day_data:
            ds = DaySummary(
                day_of_week=i - 1,
                total_distance=float(
                    day_data.total_distance
                ),
                total_duration=float(
                    day_data.total_duration
                ),
                total_elevation_gain=float(
                    day_data.total_elevation_gain
                ),
                total_calories=float(
                    day_data.total_calories
                ),
                activity_count=int(
                    day_data.activity_count
                ),
            )
            breakdown.append(ds)
            overall.total_distance += (
                ds.total_distance
            )
            overall.total_duration += (
                ds.total_duration
            )
            overall.total_elevation_gain += (
                ds.total_elevation_gain
            )
            overall.total_calories += (
                ds.total_calories
            )
            overall.activity_count += (
                ds.activity_count
            )
        else:
            breakdown.append(
                DaySummary(day_of_week=i - 1)
            )

    return WeeklySummaryResponse(
        total_distance=overall.total_distance,
        total_duration=overall.total_duration,
        total_elevation_gain=(
            overall.total_elevation_gain
        ),
        total_calories=overall.total_calories,
        activity_count=overall.activity_count,
        breakdown=breakdown,
        type_breakdown=_get_type_breakdown(
            db,
            user_id,
            start_of_week,
            end_of_week,
            activity_type,
        ),
    )

get_yearly_summary

get_yearly_summary(db, user_id, year, activity_type=None)

Get yearly activity summary for a user.

Parameters:

Name	Type	Description	Default
db	Session	Database session.	required
user_id	int	Target user ID.	required
year	int	Target calendar year.	required
activity_type	str | None	Optional activity type filter name.	None

Returns:

Type	Description
YearlySummaryResponse	Yearly summary with monthly breakdowns.

Source code in backend/app/activities/activity_summaries/crud.py

def get_yearly_summary(
    db: Session,
    user_id: int,
    year: int,
    activity_type: str | None = None,
) -> YearlySummaryResponse:
    """
    Get yearly activity summary for a user.

    Args:
        db: Database session.
        user_id: Target user ID.
        year: Target calendar year.
        activity_type: Optional activity type
            filter name.

    Returns:
        Yearly summary with monthly breakdowns.
    """
    start_of_year = date(year, 1, 1)
    end_of_year = date(year + 1, 1, 1)

    month_expr = extract(
        "month", Activity.start_time
    )

    stmt = select(
        month_expr.label("month_number"),
        func.coalesce(
            func.sum(Activity.distance), 0
        ).label("total_distance"),
        func.coalesce(
            func.sum(Activity.total_timer_time),
            0.0,
        ).label("total_duration"),
        func.coalesce(
            func.sum(Activity.elevation_gain), 0
        ).label("total_elevation_gain"),
        func.coalesce(
            func.sum(Activity.calories), 0
        ).label("total_calories"),
        func.count(Activity.id).label(
            "activity_count"
        ),
    ).where(
        Activity.user_id == user_id,
        Activity.start_time >= start_of_year,
        Activity.start_time < end_of_year,
    )

    stmt, _ = _apply_activity_type_filter(
        stmt, activity_type
    )

    stmt = stmt.group_by(month_expr).order_by(
        month_expr
    )

    monthly_results = db.execute(stmt).all()
    breakdown: list[MonthSummary] = []
    overall = SummaryMetrics()

    month_map = {
        m.month_number: m for m in monthly_results
    }

    for i in range(1, 13):
        month_data = month_map.get(i)
        if month_data:
            ms = MonthSummary(
                month_number=i,
                total_distance=float(
                    month_data.total_distance
                ),
                total_duration=float(
                    month_data.total_duration
                ),
                total_elevation_gain=float(
                    month_data.total_elevation_gain
                ),
                total_calories=float(
                    month_data.total_calories
                ),
                activity_count=int(
                    month_data.activity_count
                ),
            )
            breakdown.append(ms)
            overall.total_distance += (
                ms.total_distance
            )
            overall.total_duration += (
                ms.total_duration
            )
            overall.total_elevation_gain += (
                ms.total_elevation_gain
            )
            overall.total_calories += (
                ms.total_calories
            )
            overall.activity_count += (
                ms.activity_count
            )
        else:
            breakdown.append(
                MonthSummary(month_number=i)
            )

    return YearlySummaryResponse(
        total_distance=overall.total_distance,
        total_duration=overall.total_duration,
        total_elevation_gain=(
            overall.total_elevation_gain
        ),
        total_calories=overall.total_calories,
        activity_count=overall.activity_count,
        breakdown=breakdown,
        type_breakdown=_get_type_breakdown(
            db,
            user_id,
            start_of_year,
            end_of_year,
            activity_type,
        ),
    )

validate_view_type

validate_view_type(view_type)

Validate the view type path parameter.

Parameters:

Name	Type	Description	Default
view_type	str	The view type to validate.	required

Raises:

Type	Description
HTTPException	If the view type is not a valid option.

Source code in backend/app/activities/activity_summaries/dependencies.py

def validate_view_type(view_type: str) -> None:
    """
    Validate the view type path parameter.

    Args:
        view_type: The view type to validate.

    Raises:
        HTTPException: If the view type is not
            a valid option.
    """
    if view_type not in _VALID_VIEW_TYPES:
        raise HTTPException(
            status_code=(
                status.HTTP_422_UNPROCESSABLE_ENTITY
            ),
            detail="Invalid view type field",
        )