aioridewithgps 0.1.4

Async Python client for the Ride with GPS API

aioridewithgps

Async Python client for the Ride with GPS API v1.

This is the backend library that powers the Home Assistant Ride with GPS integration. It handles all communication with the Ride with GPS API behind the scenes.

For Home Assistant users

If you're here because you want to connect Ride with GPS to Home Assistant, you don't need to install this library yourself. Home Assistant installs it automatically when you add the integration.

What you'll need

A Ride with GPS API key. Here's how to get one:

1. Log in to your Ride with GPS account at ridewithgps.com
2. Go to your API clients page
3. Click Create a new API client
4. Give it a name (e.g., "Home Assistant")
5. Copy the API Key that appears

That's all you need before setting up the integration.

Setting up in Home Assistant

Everything is done through the Home Assistant GUI. No code, no config files, no YAML.

1. Open Home Assistant
2. Go to Settings > Devices & services
3. Click + Add integration (bottom right)
4. Search for Ride with GPS
5. A form pops up asking for three things:
   • API Key - the key you copied above
   • Email - the email you use to log in to Ride with GPS
   • Password - your Ride with GPS password
6. Click Submit

That's it. Your ride data shows up as sensors automatically.

About your password

Your password is never stored by Home Assistant or this library. Here's what actually happens:

1. When you click Submit, your password is sent to Ride with GPS one time to get an authentication token
2. Ride with GPS returns a token (a long random string) that proves you're you
3. Home Assistant saves only that token - your password is immediately discarded
4. All future API calls use the token, not your password

If the token ever stops working, Home Assistant will ask you to re-authenticate through the same form.

What sensors do you get?

Once set up, you get sensors for:

Account totals:

• Total rides, total routes
• Total distance, total elevation gain, total moving time

Your 10 most recent rides (each with):

• Ride name, date, activity type
• Distance, duration, moving time
• Elevation gain
• Average and max speed
• Average and max heart rate (if you have an HR monitor)
• Average and max power (if you have a power meter)
• Cadence, calories

Data updates automatically every 30 minutes using an efficient sync process - it only fetches what's changed, not your entire ride history every time.

---

For developers

If you want to use this library in your own Python project (outside of Home Assistant), here's how.

Installation

pip install aioridewithgps

Quick start

import asyncio
import aiohttp
from aioridewithgps import RideWithGPSClient

async def main():
    async with aiohttp.ClientSession() as session:
        # Authenticate - gets a token using your credentials.
        # The password is only used for this one call.
        auth = await RideWithGPSClient.authenticate(
            session,
            api_key="your_api_key",
            email="[e-mail]",
            password="your_password",
        )

        # Create a client using the token (not your password)
        client = RideWithGPSClient(
            session,
            api_key="your_api_key",
            auth_token=auth.auth_token,
        )

        # Now use it
        user = await client.get_user()
        print(f"Hello, {user.display_name}!")

        trips = await client.get_all_trips()
        for trip in trips[:5]:
            print(f"  {trip.name}: {trip.distance / 1000:.1f} km")

asyncio.run(main())

Available methods

Method	What it does
RideWithGPSClient.authenticate(...)	Exchange credentials for a token
client.get_user()	Get your profile
client.get_all_trips()	Get all your rides
client.get_trip(trip_id)	Get a single ride
client.get_trips(page=1)	Get one page of rides (up to 200)
client.get_all_routes()	Get all your routes
client.get_routes(page=1)	Get one page of routes (up to 200)
client.get_sync(since="2024-01-01T00:00:00Z")	Get changes since a date

Ride data fields

Every ride (TripSummary) includes:

Field	Unit	Example
name	-	"Morning Ride"
distance	meters	32186.9
duration	seconds	5400
moving_time	seconds	4800
elevation_gain	meters	305
avg_speed / max_speed	km/h	24.1 / 52.3
avg_hr / max_hr	bpm	145 / 172
avg_watts / max_watts	watts	180 / 320
calories	kcal	850
departed_at	ISO 8601	"2024-06-15T08:00:00-07:00"
activity_type	-	"Cycling"

Fields like heart rate, power, and cadence are None if those sensors weren't used on the ride.

Links

• Ride with GPS API docs: https://ridewithgps.com/api/v1/doc
• Issues: https://github.com/scriptsandthings/aioridewithgps/issues

License

MIT