Micromobility Trips

Search for available vehicles around a location. Free-floating vehicles are returned individually with live position and battery level.

{
  "location": { "latitude": 48.7466, "longitude": 9.3272 },
  "radiusMeters": 1500
}

The search radius defaults to 500 meters and is capped at 5,000. Optional filters include vehicleTypes, providers, minBatteryPercent, and limit.

Each result carries everything you need to display the vehicle:

{
  "vehicleId": "veh-8842",
  "vehicle": { "type": "SCOOTER", "propulsionType": "ELECTRIC", "name": "OKAI ES400" },
  "location": { "latitude": 48.744858, "longitude": 9.322442, "lastUpdated": "2026-07-02T08:07:50Z" },
  "isAvailable": true,
  "batteryPercent": 90,
  "provider": { "id": "pommes-sharing", "name": "POMMES Sharing" },
  "pricingPlan": {
    "planId": "plan-standard",
    "name": "Standard",
    "currency": "EUR",
    "unlockFee": { "amount": 0, "currency": "EUR" },
    "perMinuteRate": { "amount": 25, "currency": "EUR" }
  },
  "vehicleToken": "Ty9qOUtoTkxmOUpKSFpFS1ZsS1RNUT09...",
  "tokenValidUntil": "2026-07-02T08:12:50Z",
  "distanceFromSearch": 399
}

Response examples on this page show the data object. Every response is wrapped in the standard envelope { "success": true, "data": ..., "meta": ... }. All amount values are in the smallest currency unit: "amount": 25 means 0.25 EUR per minute.

Scan-to-Ride

When the user stands in front of a vehicle, skip the map: resolve the QR code sticker directly to the vehicle, including a fresh vehicleToken. Pass the scanned QR content as the {qrCode} path segment, URL-encoded if the sticker encodes a URL.

A reservation holds the vehicle while the user walks to it. The vehicle stays locked and the ride timer does not run yet.

{
  "action": "RESERVE",
  "vehicleToken": "Ty9qOUtoTkxmOUpKSFpFS1ZsS1RNUT09...",
  "userEmail": "rider@example.com",
  "userName": "Alex Rider"
}

{
  "tripId": "ADAPT2MOVE-FLEET-ZKG62KKARP",
  "status": "RESERVED",
  "provider": { "id": "pommes-sharing", "name": "POMMES Sharing" },
  "reservedUntil": "2026-07-02T08:18:34Z",
  "duration": { "activeMinutes": 0, "pausedMinutes": 0 }
}

The reservation window is set by the operator (configured per tenant) and auto-releases when it expires. Show a countdown based on reservedUntil and let the user cancel via POST /mobility-api/v2/micromobility/trips/{tripId}/cancel. The vehicle can honk during the reservation to help the rider find it (see Control the Vehicle).

userEmail identifies the rider to the mobility provider. Provide it whenever you have it, together with userName.

Starting unlocks the vehicle and starts the ride timer. Two variants:

Start a reserved trip (pass the tripId from the reservation):

{
  "action": "START",
  "tripId": "ADAPT2MOVE-FLEET-ZKG62KKARP",
  "userLocation": { "latitude": 48.7448, "longitude": 9.3224 },
  "scannedQrCode": "QR-9"
}

Start directly without a reservation (pass the vehicleToken from search):

{
  "action": "START",
  "vehicleToken": "Ty9qOUtoTkxmOUpKSFpFS1ZsS1RNUT09...",
  "userLocation": { "latitude": 48.7448, "longitude": 9.3224 },
  "userEmail": "rider@example.com"
}

userLocation is required for START. The response returns the trip with status: "ACTIVE" and startedAt.

During an active trip, the rider can act on the vehicle directly:

{
  "action": "HONK"
}

Vehicle actions execute asynchronously on the vehicle. The API answers with 202 Accepted once the command is handed to the provider:

{
  "tripId": "ADAPT2MOVE-FLEET-ZKG62KKARP",
  "action": "HONK",
  "acceptedAt": "2026-07-02T08:08:35Z"
}

Ending the trip locks the vehicle, stops the timer, and settles the price.

{
  "endLocation": { "latitude": 48.7402, "longitude": 9.3155 }
}

The response returns the completed trip with status: "COMPLETED", the ride duration, and the price breakdown (unlock fee plus per-minute charges). Show this as the trip receipt.