Activities API reference

Activity streams

Activity streams sub-module for time-series stream data.

Heart rate, power, cadence, elevation, speed, pace and map streams, plus the visibility filtering applied before a stream is served.

This package exports nothing from __init__; other modules use it only through integration_service (see tests/architecture).

Activity summary

FastAPI routes for activity summaries (authenticated).

Thin HTTP adapter: it validates query parameters and delegates every decision to :mod:activity_summary_service. Mounted under /activities/summaries as a sub-resource of activities, and the period is a query parameter, not a path segment, because week/month/ year/lifetime are four views of one resource, not four resources.

read_activity_summary

read_activity_summary(_check_scopes, token_user_id, db, period='week', anchor_date=None, target_year=None, activity_type=None)

Return the authenticated user's activity summary for one period.

Source code in backend/app/modules/activities/activity/summary_router.py

@router.get(
    "",
    response_model=activity_summary_schema.SummaryResponse,
)
def read_activity_summary(
    _check_scopes: Annotated[Callable, Security(auth_dependencies.check_scopes, scopes=["activities:read"])],
    token_user_id: Annotated[int, Depends(auth_dependencies.get_sub_from_access_token)],
    db: Annotated[Session, Depends(core_database.get_db)],
    period: Annotated[str, Query(pattern="^(week|month|year|lifetime)$")] = "week",
    anchor_date: Annotated[
        date | None,
        Query(
            alias="date",
            description=(
                "The caller's local calendar date, used to decide which week or month "
                "is current. Defaults to today in the caller's configured timezone."
            ),
        ),
    ] = None,
    target_year: Annotated[
        int | None,
        Query(alias="year", description="Target year for the yearly summary. Defaults to the anchor date's year."),
    ] = None,
    activity_type: Annotated[
        str | None,
        Query(alias="type", description="Filter the summary by activity type name."),
    ] = None,
) -> activity_summary_schema.SummaryResponse:
    """Return the authenticated user's activity summary for one period."""
    return activity_summary_service.build_summary(
        token_user_id,
        period,
        db,
        anchor=anchor_date,
        target_year=target_year,
        activity_type=activity_type,
    )

Activity workout steps

Activity workout steps sub-module.

Step duration, targets, intensity and exercise details for structured workouts.

This package exports nothing from __init__; other modules use it only through integration_service (see tests/architecture).

Activity file import

Pure parsers turning activity file bytes into the canonical parsed contract.

.gpx / .tcx / .fit in, ParsedFile out. Pure by contract: no database, no privacy settings, no gear lookup, no provider client, no HTTP — which is what makes a parser testable with bytes alone. The domain context a parsed activity needs (owner privacy defaults, gear, provider ids) is re-attached afterwards by activity_ingestion.enrichment_service, and the activity-file-import-purity import-linter contract keeps it that way.

Callers outside this package use :mod:integration_service (get_parser, supported_extensions); the parser modules and registry are private to it. Importing this package does not pull in a parser.