Custom Routes and Group Rides API

Find cycling events, group rides, and leisure routes near a location

Overview

Get events within a specified radius of a location. Returns upcoming/ongoing events, leisure routes (permanent routes), and recently completed events (within last 14 days).

Authentication

This endpoint is public and does not require authentication.

Query Parameters

latitude · number · required

User’s latitude (-90 to 90)

longitude · number · required

User’s longitude (-180 to 180)

radius · number · default: "1000"

Search radius in meters (default: 1000m)

city · string

Filter by city name (case-insensitive). Uses the auto-computed city field from route geometry.

categories · string

Comma-separated list of category names to filter by (e.g., “Group Ride,Social”)

Response

Returns an object with an events array containing event details:

events · array

Array of event objects

Show Event Object

id · number

Unique event identifier

name · string

Event name

alias · string

URL-friendly alias for the event (e.g., “central-park-morning-ride”)

description · string

Event description

emoji · string

Event emoji icon

image_url · string

Event cover image URL

start_time · string

ISO 8601 datetime (null for leisure routes)

end_time · string

ISO 8601 datetime (null for leisure routes)

created_by · string

Auth0 user ID of the event creator

created_at · string

ISO 8601 datetime when the event was created

updated_at · string

ISO 8601 datetime when the event was last updated

distance · number

Distance from query location in miles

visits_total · number

Total number of unique users who completed this event

is_leisure_route · boolean

True if this is a permanent leisure route (no start/end times)

city · string

City name (automatically determined from route start point using PostGIS).

This field is computed from the event’s route geometry by finding the closest city border. Returns null if the event has no route geometry. Uses spatial index (GIST) for efficient lookups.

destination · object

DEPRECATED: Use the top-level city field instead. This field will be removed in a future version.

Destination information (if event is destination-based)

Show Destination Object

id · number

Destination ID

name · string

Destination name

latitude · number

Destination latitude

longitude · number

Destination longitude

area_name · string

Area name

city · string

City name

categories · array

Array of category objects

route · object

Route information (if event has a route)

Show Route Object

distance · number

Route distance in meters

duration · number

Estimated duration in seconds

polyline · string

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

categories · array

Array of category objects with id, name, and emoji

images · array

Array of event images with image_url and created_at

Request Example

cURL

curl "https://api.cyclemate.com/events/nearby/?latitude=40.7589&longitude=-73.9851&radius=5000&city=New%20York%20City" \
  -H "Content-Type: application/json"

JavaScript

const response = await fetch(
  'https://api.cyclemate.com/events/nearby/?latitude=40.7589&longitude=-73.9851&radius=5000',
  {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
    },
  }
);

const data = await response.json();
console.log(data.events);

Python

import requests

url = "https://api.cyclemate.com/events/nearby/"
params = {
    "latitude": 40.7589,
    "longitude": -73.9851,
    "radius": 5000
}

response = requests.get(url, params=params)
events = response.json()["events"]

Response Example

{
  "events": [
    {
      "id": 123,
      "name": "Central Park Morning Ride",
      "alias": "central-park-morning-ride",
      "description": "Casual group ride through Central Park",
      "emoji": "🚴",
      "image_url": "https://storage.googleapis.com/events/123.jpg",
      "start_time": "2025-11-15T08:00:00Z",
      "end_time": "2025-11-15T10:00:00Z",
      "created_by": "google-oauth2|115315991711634062214",
      "created_at": "2025-11-01T10:00:00Z",
      "updated_at": "2025-11-01T10:00:00Z",
      "distance": 0.8,
      "visits_total": 42,
      "is_leisure_route": false,
      "city": "New York City",
      "destination": {
        "id": 45,
        "name": "Central Park",
        "latitude": 40.785091,
        "longitude": -73.968285,
        "area_name": "Manhattan",
        "city": "New York City",
        "categories": [
          {
            "id": 1,
            "name": "Park",
            "emoji": "🌳"
          }
        ]
      },
      "categories": [
        {
          "id": 2,
          "name": "Group Ride",
          "emoji": "👥"
        }
      ],
      "images": [
        {
          "image_url": "https://storage.googleapis.com/event-photos/1.jpg",
          "created_at": "2025-11-01T10:00:00Z"
        }
      ]
    }
  ]
}

Event Ordering

Events are returned in the following order:

1. Upcoming/Ongoing Events - Events that haven’t ended yet, sorted by distance
2. Leisure Routes - Permanent routes with no time restrictions, sorted by distance
3. Recent Past Events - Events that ended within the last 14 days, sorted by distance

Notes

• Distance is calculated to the event’s destination (for destination-based events) or to the route geometry (for route-based events)
• When both city and area filters are provided, events must match both criteria
• Category filtering is inclusive (events matching any of the specified categories will be returned)
• Leisure routes are always included regardless of their start/end times being null