# Strava Integration via LowCodeAPI

## Overview

Strava is a fitness tracking platform for athletes and fitness enthusiasts. The Strava API provides comprehensive functionality for:

- **Activities** - Log and retrieve athletic activities (runs, rides, etc.)
- **Athletes** - Access athlete profiles and statistics
- **Routes** - Manage and share running/cycling routes
- **Segments** - Access segment leaderboards and efforts
- **Clubs** - Manage clubs and group activities
- **Webhooks** - Receive real-time activity updates

## Base Endpoint

```
https://api.lowcodeapi.com/strava/
```

## Authentication

LowCodeAPI handles authentication automatically using OAuth2.0. You only need to:

1. **Create an app** at [Strava Developers](https://www.strava.com/settings/api) to get your Client ID and Secret
2. **Connect your account** in the LowCodeAPI dashboard
3. **Use your `api_token`** in all requests

The `api_token` is your LowCodeAPI authentication token. LowCodeAPI will automatically:
- Fetch your Strava access token
- Apply it to each request as a Bearer token

**Auth Type**: OAuth2.0 (Bearer Token)
**Scopes**: read, read_all, profile:read_all, activity:read, activity:read_all

## API Categories

- **Utilities** - Fitness tracking and athletic activities

## Common Endpoints

### Category: Activities

#### Create Activity

**Method**: `POST` | **LowCodeAPI Path**: `/api/v3/activities`

**Full URL**:
```
https://api.lowcodeapi.com/strava/api/v3/activities?api_token={api_token}
```

**Description**: Create a new manual activity.

**Request Body**:
```json
{
  "name": "Morning Run",
  "type": "Run",
  "sport_type": "Run",
  "start_date_local": "2024-01-30T08:00:00Z",
  "elapsed_time": 3600,
  "description": "A nice morning run in the park",
  "distance": 5000.5
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Activity name |
| `type` | string | No | Activity type (Run, Ride, etc.) |
| `sport_type` | string | Yes | Sport type (Run, MountainBikeRide, etc.) |
| `start_date_local` | string | Yes | ISO 8601 formatted date time |
| `elapsed_time` | integer | Yes | Duration in seconds |
| `description` | string | No | Activity description |
| `distance` | number | No | Distance in meters |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/strava/api/v3/activities?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Morning Run",
    "sport_type": "Run",
    "start_date_local": "2024-01-30T08:00:00Z",
    "elapsed_time": 3600,
    "distance": 5000.5
  }'
```

**Official Documentation**: [Create Activity](https://developers.strava.com/docs/reference/#api-Activities-createActivity)

---

#### Get Activity

**Method**: `GET` | **LowCodeAPI Path**: `/api/v3/activities/activity_id`

**Full URL**:
```
https://api.lowcodeapi.com/strava/api/v3/activities/activity_id?id={activity_id}&api_token={api_token}
```

**Description**: Retrieve a specific activity by ID.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Activity ID |
| `include_all_efforts` | boolean | No | Include segment efforts (default: false) |

**Example Request**:
```bash
# Replace ACTIVITY_ID with actual activity ID
curl -X GET "https://api.lowcodeapi.com/strava/api/v3/activities/activity_id?id=ACTIVITY_ID&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Get Activity](https://developers.strava.com/docs/reference/#api-Activities-getActivityById)

---

#### List Athlete Activities

**Method**: `GET` | **LowCodeAPI Path**: `/api/v3/athlete/activities`

**Full URL**:
```
https://api.lowcodeapi.com/strava/api/v3/athlete/activities?api_token={api_token}
```

**Description**: List activities for the authenticated athlete.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `before` | integer | No | Unix timestamp (only activities before this time) |
| `after` | integer | No | Unix timestamp (only activities after this time) |
| `page` | integer | No | Page number |
| `per_page` | integer | No | Number of activities per page (max: 200) |

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/strava/api/v3/athlete/activities?per_page=50&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [List Activities](https://developers.strava.com/docs/reference/#api-Activities-getLoggedInAthleteActivities)

---

### Category: Athletes

#### Get Athlete Profile

**Method**: `GET` | **LowCodeAPI Path**: `/api/v3/athlete`

**Full URL**:
```
https://api.lowcodeapi.com/strava/api/v3/athlete?api_token={api_token}
```

**Description**: Retrieve the profile of the authenticated athlete.

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/strava/api/v3/athlete?api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Get Athlete](https://developers.strava.com/docs/reference/#api-Athletes-getLoggedInAthlete)

---

#### Get Athlete Stats

**Method**: `GET` | **LowCodeAPI Path**: `/api/v3/athletes/athlete_id/stats`

**Full URL**:
```
https://api.lowcodeapi.com/strava/api/v3/athletes/athlete_id/stats?id={athlete_id}&api_token={api_token}
```

**Description**: Retrieve statistics for a specific athlete.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Athlete ID |

**Example Request**:
```bash
# Replace ATHLETE_ID with actual athlete ID
curl -X GET "https://api.lowcodeapi.com/strava/api/v3/athletes/athlete_id/stats?id=ATHLETE_ID&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Get Stats](https://developers.strava.com/docs/reference/#api-Athletes-getStats)

---

### Category: Routes

#### Get Athlete Routes

**Method**: `GET` | **LowCodeAPI Path**: `/api/v3/athletes/athlete_id/routes`

**Full URL**:
```
https://api.lowcodeapi.com/strava/api/v3/athletes/athlete_id/routes?id={athlete_id}&api_token={api_token}
```

**Description**: List routes for a specific athlete.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Athlete ID |

**Example Request**:
```bash
# Replace ATHLETE_ID with actual athlete ID
curl -X GET "https://api.lowcodeapi.com/strava/api/v3/athletes/athlete_id/routes?id=ATHLETE_ID&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Get Routes](https://developers.strava.com/docs/reference/#api-Routes-getRoutesByAthleteId)

---

## Usage Examples

### Example 1: Log Activity

Create a new activity:

```bash
# Create a new running activity
# No ID needed - creates new activity
curl -X POST "https://api.lowcodeapi.com/strava/api/v3/activities?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Morning Run",
    "sport_type": "Run",
    "start_date_local": "2024-01-30T08:00:00Z",
    "elapsed_time": 3600,
    "distance": 10000,
    "description": "Great 10K run in the park"
  }'
```

### Example 2: Retrieve Activities

Get recent activities:

```bash
# Get authenticated athlete's recent activities
# No ID needed - lists current athlete's activities
curl -X GET "https://api.lowcodeapi.com/strava/api/v3/athlete/activities?per_page=50&api_token=YOUR_API_TOKEN"

# Get specific activity details
# Replace ACTIVITY_ID with actual activity ID
curl -X GET "https://api.lowcodeapi.com/strava/api/v3/activities/activity_id?id=ACTIVITY_ID&api_token=YOUR_API_TOKEN"
```

### Example 3: Get Athlete Stats

View athlete statistics:

```bash
# Get athlete profile
# No ID needed - returns authenticated athlete
curl -X GET "https://api.lowcodeapi.com/strava/api/v3/athlete?api_token=YOUR_API_TOKEN"

# Get athlete statistics
# Replace ATHLETE_ID with actual athlete ID
curl -X GET "https://api.lowcodeapi.com/strava/api/v3/athletes/athlete_id/stats?id=ATHLETE_ID&api_token=YOUR_API_TOKEN"
```

## Complete Endpoint Reference

For a complete list of all 34 endpoints and their parameters, refer to:

- **OpenAPI Definition**: https://backend.lowcodeapi.com/strava/definition
- **Official Strava Documentation**: https://developers.strava.com/docs/reference

## Rate Limits & Best Practices

- **Rate Limit**: 100 requests per 15 minutes, 1000 requests per day
- **Best Practices**:
  - Store activity and athlete IDs for efficient updates
  - Use pagination for large activity lists
  - Implement proper date filtering for activity queries
  - Cache athlete profile information
  - Use webhooks for real-time activity updates
  - Handle rate limiting with exponential backoff

## Error Handling

All responses are wrapped in a `data` key:
```json
{
  "data": {
    // Actual response from Strava
  }
}
```

Common errors:
- **400**: Invalid request parameters
- **401**: Invalid or expired access token
- **404**: Activity or athlete not found
- **429**: Rate limit exceeded
- **503**: Service temporarily unavailable