Get User Routes

Retrieve a paginated list of routes for the authenticated user

Overview

Get all routes (ride history) for the currently authenticated user. Returns a paginated list of routes ordered by date (most recent first).

Authentication

Required: This endpoint requires Auth0 authentication. Include a valid JWT token in the Authorization header.

The routes returned will automatically be filtered to only include routes belonging to the authenticated user.

Query Parameters

page · number · default: "1"

Page number for pagination (1-based indexing)

limit · number · default: "10"

Number of routes per page (default: 10)

Response

Returns an array of route objects:

routes · array

Array of route history objects, ordered by date_started (most recent first)

Show Route Object

id · number

Unique route identifier

date_started · string

ISO 8601 datetime when the ride started

local_timezone · string

IANA timezone identifier where the ride took place (e.g., “America/Los_Angeles”)

polyline · string

Encoded polyline representation of the route path (Google Encoded Polyline, precision 5)

destination_name · string

Name of the destination (if applicable)

destination_address · string

Address of the destination (if applicable)

distance_traveled · number

Distance traveled in meters

duration_traveled · number

Duration of the ride in seconds

completed · boolean

Whether the ride was completed

event · object

Event information if the route was associated with an event (complete EventSerializer data)

weather_conditions · array

Array of weather condition strings (e.g., [“Clear”, “Cold”])

temperature · number

Temperature in Fahrenheit at the time/location of the ride

wind_speed · number

Wind speed in mph

weather_fetched_at · string

ISO 8601 datetime when weather data was retrieved

weather_display · string

Human-readable weather description (e.g., “Sunny, Windy (69°F)”)

images · array

Array of route images with image_url and created_at

welcome_message · string

Optional welcome or completion message for the route

Request Example

cURL

curl "https://api.cyclemate.com/user/routes/?page=1&limit=20" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

JavaScript

const response = await fetch(
  'https://api.cyclemate.com/user/routes/?page=1&limit=20',
  {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${yourJwtToken}`,
    },
  }
);

const routes = await response.json();
console.log(`Retrieved ${routes.length} routes`);

Python

import requests

url = "https://api.cyclemate.com/user/routes/"
params = {
    "page": 1,
    "limit": 20
}
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {your_jwt_token}"
}

response = requests.get(url, params=params, headers=headers)
routes = response.json()

Response Example

[
  {
    "id": 1234,
    "date_started": "2025-11-13T14:30:00Z",
    "local_timezone": "America/New_York",
    "polyline": "encoded_polyline_string_here",
    "destination_name": "Central Park",
    "destination_address": "Central Park, New York, NY",
    "distance_traveled": 5280.5,
    "duration_traveled": 1267,
    "completed": true,
    "event": {
      "id": 123,
      "name": "Central Park Morning Ride",
      "alias": "central-park-morning-ride",
      "emoji": "🚴",
      "start_time": "2025-11-13T08:00:00Z",
      "end_time": "2025-11-13T10:00:00Z",
      "created_by": "google-oauth2|115315991711634062214",
      "destination": {
        "id": 45,
        "name": "Central Park",
        "latitude": 40.785091,
        "longitude": -73.968285
      }
    },
    "weather_conditions": ["Clear", "Mild"],
    "temperature": 68.5,
    "wind_speed": 5.2,
    "weather_fetched_at": "2025-11-13T14:30:00Z",
    "weather_display": "Clear, Mild (69°F)",
    "images": [
      {
        "image_url": "https://storage.googleapis.com/route-photos/1234-1.jpg",
        "created_at": "2025-11-13T14:45:00Z"
      }
    ],
    "welcome_message": "Great ride! You completed the Central Park Morning Ride event."
  },
  {
    "id": 1233,
    "date_started": "2025-11-12T09:15:00Z",
    "local_timezone": "America/New_York",
    "polyline": "encoded_polyline_string_here",
    "destination_name": "Brooklyn Bridge",
    "destination_address": null,
    "distance_traveled": 3520.0,
    "duration_traveled": 845,
    "completed": true,
    "event": null,
    "weather_conditions": ["Cloudy"],
    "temperature": 62.0,
    "wind_speed": 8.1,
    "weather_fetched_at": "2025-11-12T09:15:00Z",
    "weather_display": "Cloudy (62°F)",
    "images": [],
    "welcome_message": null
  }
]

Error Responses

User Not Found (404)

{
  "error": "User not found"
}

Unauthorized (401)

{
  "error": "Authentication credentials were not provided."
}

Pagination

• Results are paginated to improve performance
• Default page size is 10 routes
• Use page parameter to navigate through pages
• Use limit parameter to adjust page size (max recommended: 50)
• Routes are ordered by date_started in descending order (newest first)

Notes

• Only routes belonging to the authenticated user are returned
• The event field includes complete event details if the route was associated with an event
• Weather data is automatically fetched at the time of route creation
• Images are limited to the most recent 50 per route
• The completed field indicates whether the user finished the ride
• Distance is in meters, duration is in seconds
• Temperature is in Fahrenheit, wind speed is in mph

Use Cases

• Activity History: Display a user’s ride history in their profile
• Statistics Dashboard: Calculate total distance, rides, etc.
• Route Replay: Visualize past rides on a map
• Challenge Progress: Show which routes contributed to challenges
• Weather Insights: Analyze riding patterns based on weather conditions