Skip to main content
GET
/
cities
/
{city_name}
/
events
/
{
  "city": "<string>",
  "center": {
    "latitude": 123,
    "longitude": 123
  },
  "radius_miles": 123,
  "count": 123,
  "events": [
    {
      "id": 123,
      "name": "<string>",
      "alias": "<string>",
      "distance": 123,
      "description": "<string>",
      "emoji": "<string>",
      "image_url": "<string>",
      "start_time": "<string>",
      "end_time": "<string>",
      "is_happening_now": true,
      "is_future": true,
      "is_leisure_route": true,
      "visits_total": 123,
      "city": "<string>",
      "destination": {},
      "route": {},
      "categories": [
        {}
      ],
      "images": [
        {}
      ],
      "created_by": {}
    }
  ]
}

​
Overview

Get all events for a specific city. This endpoint automatically uses the city’s geographic center and searches within a 50-mile radius. Returns upcoming/ongoing events first, then leisure routes, then recently completed events (last 14 days).

​
Authentication

Public API: No authentication required.

​
Path Parameters

​
city_name
string
required
Name of the city (case-insensitive). Examples: "San Francisco", "New York City", "Los Angeles"

​
Query Parameters

​
categories
string
Comma-separated list of category names to filter by (case-insensitive)Example: "Group Ride,Social", "Commute"

​
Response

Returns events sorted by relevance (upcoming → leisure → recent past) and distance from city center:
​
city
string
Name of the city
​
center
object
Calculated geographic center of the city
​
radius_miles
number
Search radius in miles (always 50)
​
count
number
Total number of events returned
​
events
array
Array of event objects, each with complete event details including:

​
Request Examples

cURL
# Basic: Get all events for San Francisco
curl "https://api.cyclemate.com/cities/San%20Francisco/events/"

# Filter by categories
curl "https://api.cyclemate.com/cities/New%20York%20City/events/?categories=Group%20Ride,Social"
JavaScript
// Get all events for a city
const response = await fetch(
  'https://api.cyclemate.com/cities/San Francisco/events/'
);
const data = await response.json();
console.log(`Found ${data.count} events in ${data.city}`);
console.log(`City center: ${data.center.latitude}, ${data.center.longitude}`);

// With category filter
const filtered = await fetch(
  'https://api.cyclemate.com/cities/San Francisco/events/?categories=Commute'
);
Python
import requests

# Basic city events
city_name = "San Francisco"
url = f"https://api.cyclemate.com/cities/{city_name}/events/"
response = requests.get(url)
data = response.json()
print(f"Found {data['count']} events in {data['city']}")

# With category filter
params = {
    "categories": "Group Ride,Social"
}
response = requests.get(url, params=params)

​
Response Example

{
  "city": "San Francisco",
  "center": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "radius_miles": 50,
  "count": 12,
  "events": [
    {
      "id": 456,
      "name": "Golden Gate Bridge Sunset Ride",
      "alias": "golden-gate-bridge-sunset-ride",
      "distance": 2.3,
      "description": "Watch the sunset from the Golden Gate Bridge",
      "emoji": "🌅",
      "image_url": "https://storage.googleapis.com/events/456.jpg",
      "start_time": "2025-11-20T18:00:00Z",
      "end_time": "2025-11-20T20:00:00Z",
      "is_happening_now": false,
      "is_future": true,
      "is_leisure_route": false,
      "visits_total": 45,
      "city": "San Francisco",
      "destination": {
        "id": 78,
        "name": "Golden Gate Bridge",
        "area_name": "Marina District",
        "city": "San Francisco",
        "latitude": 37.8199,
        "longitude": -122.4783
      },
      "route": {
        "distance": 8500,
        "duration": 2038,
        "polyline": "encoded_polyline_string..."
      },
      "categories": [
        {
          "id": 2,
          "name": "Group Ride",
          "emoji": "👥"
        }
      ],
      "images": [],
      "created_by": {
        "auth0_user_id": "google-oauth2|115315991711634062214",
        "name": "John Doe",
        "image_url": "https://storage.googleapis.com/users/profile.jpg",
        "date_registered": "2025-01-15T10:30:00Z"
      }
    }
    // ... more events
  ]
}

​
Error Responses

​
City Not Found (404)

{
  "error": "City 'Unknown City' not found"
}

​
No Coordinates Available (404)

{
  "error": "No coordinates available for city 'San Francisco'"
}

​
How It Works

  1. City Lookup: Finds the city by name (case-insensitive)
  2. Center Calculation: Computes the geographic center from all areas/neighborhoods in the city
  3. Radius: Uses a fixed 50-mile radius from the city center
  4. Event Partitioning:
    • Upcoming/ongoing events (end_time > now)
    • Leisure routes (permanent routes, no time restrictions)
    • Recent past events (ended within last 14 days)
  5. Filtering: Applies city filter (always) plus optional category filter
  6. Sorting: Orders by relevance (upcoming → leisure → past) then by distance from center

​
Key Features

  • No Coordinates Required: Just provide the city name
  • Automatic Center: Calculates city center from its areas
  • Wide Coverage: 50-mile radius captures entire metro area
  • Smart Ordering: Most relevant events first
  • Optional Category Filter: Narrow down by event categories
  • Distance Info: Each event includes distance from city center

​
Use Cases

  • City Landing Pages: Show all events in a city
  • Browse by Location: Let users explore events by city
  • Metro-Wide Discovery: Find events across entire metropolitan area
  • Regional Marketing: Promote events for specific cities
  • Mobile App: City selection screen → events list

​
Notes

  • City name matching is case-insensitive: "san francisco" = "San Francisco" = "SAN FRANCISCO"
  • The 50-mile radius is fixed and cannot be customized (use /events/nearby/ for custom radius)
  • Events are always filtered by city (only returns events in the specified city)
  • The city center is calculated as the average of all area coordinates within the city
  • Distance is measured from city center to event destination or route geometry