Unit Conversions in Stravalib#

Stravalib uses the Pint library for unit conversions, making it easy to work with Strava’s metric data in your preferred units.

Quick Start#

The stravalib.unit_helper module provides convenient conversion functions:

from stravalib import unithelper as uh

# Distance conversions
distance_meters = 5000  # Strava returns distance in meters
uh.miles(distance_meters)  # <Quantity(3.10686, 'mile')>
uh.kilometers(distance_meters)  # <Quantity(5.0, 'kilometer')>
uh.feet(distance_meters)  # <Quantity(16404.2, 'foot')>

# Speed conversions
speed_mps = 3.5  # Strava returns speed in meters/second
uh.mph(speed_mps)  # <Quantity(7.83, 'mile/hour')>
uh.kph(speed_mps)  # <Quantity(12.6, 'kilometer/hour')>

# Weight conversions
weight_kg = 70  # Strava returns weight in kilograms
uh.pounds(weight_kg)  # <Quantity(154.324, 'pound')>

# Temperature conversions
temp_c = 20  # Strava returns temperature in Celsius
uh.c2f(temp_c)  # 68.0 (Fahrenheit)

Working with Activity Data#

When you fetch activities from Strava, many fields come with units attached:

from stravalib.client import Client

client = Client(access_token="your_token")
activity = client.get_activity(123456789)

# Distance (returned in meters)
print(activity.distance)  # 5000.0
print(uh.miles(activity.distance))  # <Quantity(3.10686, 'mile')>
print(uh.kilometers(activity.distance))  # <Quantity(5.0, 'kilometer')>

# Speed (returned in meters/second)
print(activity.average_speed)  # 3.5
print(uh.mph(activity.average_speed))  # <Quantity(7.83, 'mile/hour')>
print(uh.kph(activity.average_speed))  # <Quantity(12.6, 'kilometer/hour')>

# Elevation (returned in meters)
print(activity.total_elevation_gain)  # 150.0
print(uh.feet(activity.total_elevation_gain))  # <Quantity(492.126, 'foot')>

Available Conversion Functions#

Distance#

  • meter(s) - Convert to meters

  • kilometer(s) - Convert to kilometers

  • mile(s) - Convert to miles

  • foot/feet - Convert to feet

Speed#

  • meters_per_second - Convert to m/s

  • mph or miles_per_hour - Convert to miles per hour

  • kph or kilometers_per_hour - Convert to kilometers per hour

Weight#

  • kilogram(s) or kg(s) - Convert to kilograms

  • pound(s) or lb(s) - Convert to pounds

Time#

  • second(s) - Convert to seconds

  • hour(s) - Convert to hours

Temperature#

  • c2f(celsius) - Convert Celsius to Fahrenheit

Using Pint Directly#

For more advanced conversions, you can use Pint directly:

from stravalib.unit_registry import ureg

# Create quantities
distance = ureg.Quantity(5000, "meter")
speed = ureg.Quantity(3.5, "meter/second")

# Convert to any unit
distance.to("mile")  # <Quantity(3.10686, 'mile')>
distance.to("yard")  # <Quantity(5468.07, 'yard')>
speed.to("kilometer/hour")  # <Quantity(12.6, 'kilometer/hour')>
speed.to("mile/hour")  # <Quantity(7.83, 'mile/hour')>

# Perform calculations
pace = (1 / speed).to("minute/kilometer")  # Calculate pace
print(pace)  # <Quantity(4.76, 'minute/kilometer')>

Common Patterns#

Converting Multiple Activities#

activities = client.get_activities(limit=10)

for activity in activities:
    distance_mi = uh.miles(activity.distance)
    speed_mph = uh.mph(activity.average_speed)
    elevation_ft = uh.feet(activity.total_elevation_gain)

    print(f"{activity.name}: {distance_mi:.2f} mi @ {speed_mph:.2f} mph")

Calculating Pace#

# Strava provides speed, but runners often want pace
activity = client.get_activity(123456789)

# Convert speed (m/s) to pace (min/km or min/mile)
from stravalib.unit_registry import ureg

speed = ureg.Quantity(activity.average_speed, "meter/second")
pace_per_km = (1 / speed).to("minute/kilometer")
pace_per_mile = (1 / speed).to("minute/mile")

print(f"Pace: {pace_per_km:.2f} min/km or {pace_per_mile:.2f} min/mile")

Formatting Output#

# Get just the numeric value
distance_mi = uh.miles(activity.distance)
print(f"Distance: {distance_mi.magnitude:.2f} miles")

# Or use the full quantity
print(f"Distance: {distance_mi:.2f}")  # Includes unit

Tips#

  1. Strava’s Default Units: Strava API returns:

    • Distance in meters

    • Speed in meters/second

    • Elevation in meters

    • Weight in kilograms

    • Temperature in Celsius

  2. Chaining Conversions: You can convert between any compatible units:

    # Convert meters -> feet -> yards
distance = uh.meters(5000)
distance.to("foot").to("yard")

  3. Unit Arithmetic: Pint quantities support math operations:

    total_distance = uh.miles(5) + uh.kilometers(3)
print(total_distance.to("mile"))  # Automatically converts

See Also#