# aioridewithgps

Async Python client for the [Ride with GPS](https://ridewithgps.com) API v1.

This is the backend library that powers the **[Home Assistant](https://www.home-assistant.io/) 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](https://ridewithgps.com)
2. Go to your [API clients page](https://ridewithgps.com/api/api_clients)
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

```bash
pip install aioridewithgps
```

### Quick start

```python
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="your_email@example.com",
            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
