Real-Time Data Feed

Velolink provides a real-time WebSocket data feed for live usage updates. This guide will walk you through connecting to and consuming the live data feed.

Prerequisites

Before connecting to the live data feed, ensure you have:

1. Your namespace identifier (found in the admin panel under your user profile)
2. An API token with the velolink.data permission or the Velolink READ Data role

Connection Steps

1. Obtain API Token

First, you'll need to retrieve an API token from the Velolink Console.

2. Verify Permissions

Ensure your API token has the required permissions (velolink.data) to access the data feed.

3. Connect to WebSocket

The WebSocket endpoint follows this format:

ws://feed.velolink.cloud/agents/velolink-latest-data/[namespace]

Replace [namespace] with your namespace identifier.

Include your API token in the connection headers:

const headers = {
  "X-ApiToken": "your-api-token-here",
};

Example Data Structure

The WebSocket feed delivers JSON messages with the following structure:

{
  "type": "cf_agent_state",
  "state": {
    "data": {
      "915": {
        "vehicleId": "915",
        "namespace": "mynamespace",
        "operator": "DT",
        "routeId": "Green Line",
        "tripId": "3732174",
        "features": ["cyclist", "priority"],
        "featureData": {
          "cyclist": {
            "deployed": true,
            "capacity": 3,
            "available": 2,
            "used": 1,
            "type": "cyclist",
            "rideStart": false,
            "rideEnd": false
          },
          "priority": {
            "capacity": 2,
            "available": 1,
            "used": 1,
            "type": "priority",
            "rideStart": false,
            "rideEnd": false
          }
        },
        "lat": 37.41038131713867,
        "long": -121.95980072021484,
        "timestamp": "2025-04-16T15:15:53.405Z",
        "events": []
      }
    }
  }
}

Data Fields

• type: Message type identifier
• state.data: Object containing vehicle data, keyed by vehicle ID
• For each vehicle:
  • vehicleId: Unique identifier for the vehicle
  • namespace: Organization namespace
  • operator: Transit operator name
  • routeId: Current route identifier (may be empty string if not on route)
  • tripId: Current trip identifier (may be empty string if not on trip)
  • features: Array of available features (e.g., ["cyclist", "priority"])
  • featureData: Detailed feature information:
    • cyclist: Bicycle rack information
      • deployed: Boolean indicating if rack is deployed
      • capacity: Total bicycle capacity
      • available: Number of available spots
      • used: Number of spots in use
      • type: Feature type identifier
      • rideStart: Boolean indicating start of ride
      • rideEnd: Boolean indicating end of ride
    • priority: Priority seating information
      • capacity: Total priority seating capacity
      • available: Number of available priority seats
      • used: Number of priority seats in use
      • type: Feature type identifier
      • rideStart: Boolean indicating start of ride
      • rideEnd: Boolean indicating end of ride
  • lat: Latitude coordinate
  • long: Longitude coordinate
  • timestamp: UTC timestamp of the data point
  • events: Array of recent events for the vehicle

Information Information

info

• All timestamps are in ISO 8601 format with UTC timezone
• The WebSocket connection requires a valid API token with the velolink.data permission
• Data is streamed in real-time as vehicles update their status
• Each message contains the complete state for all vehicles in your namespace
• Vehicles may have multiple features (e.g., cyclist racks and priority seating)
• Empty route and trip IDs indicate the vehicle is not currently in service
• Feature status (deployed, rideStart, rideEnd) helps track usage patterns

Error Handling

Common WebSocket connection errors:

• 401: Invalid or missing API token

tip

It's recommended to implement reconnection logic in case of connection drops or errors.