public-api-docs

User API Radar Guide

Overview

Radars let a user save a temporary vehicle-availability alert for an area. If no suitable vehicle is available where the user wants to rent, the app can create a radar with a center point and radius. The backend monitors the area and notifies the user when an available free-floating vehicle appears before the radar expires.

Use radars for “notify me when a vehicle is nearby” experiences. Do not use them as a replacement for normal map discovery. The user should first search vehicles with the efficient GET /vehicles viewport flow, then create a radar only when the map has no useful result.

Related reference: User API User API Guide Discovery And Vehicle Guide

Core Concepts

Radar Area

A radar area is defined by:

Field Meaning
position GeoJSON point for the center of the search area. Coordinates are [lng, lat].
radius Search radius in meters.
startTime When the radar should become active.
endTime Returned by the backend. On create, the backend derives it from the tenant radar duration setting.
address Returned by the backend when reverse geocoding is available.

Default tenant behavior is a 60-minute radar duration and a maximum radius of 5,000 meters, but operators can configure these values. If the requested radius is too large, the API rejects the request with the radar maximum-radius error.

Radar Lifecycle

From the user’s point of view, a radar has four lifecycle outcomes:

Outcome What happens
Active The radar exists and is still watching the area.
Delivered A suitable vehicle was found and a notification was sent.
Canceled The user deleted the radar before it completed.
Expired The radar reached its end time without finding a vehicle.

The User API response exposes the active radar’s id, startTime, endTime, address, position, and radius. Apps should treat a radar that disappears from the active list as completed, canceled, or expired, depending on the action the user took and whether the user received a notification.

One Active Radar Window

A user cannot create overlapping active radar windows. If the user already has an active radar for the same time window, creating or updating another one fails with the “already have active radar” error.

Design the UI around one current alert:

Common User Workflow

Create A Vehicle Radar

Use this flow when a user is looking at a map area and there is no suitable vehicle available:

  1. Query vehicles with GET /vehicles using viewport-derived lat, lng, and rad.
  2. If the result is empty or not useful, offer “Notify me when a vehicle is nearby”.
  3. Ask for, or infer, the radar center from the current map center or the user’s selected point.
  4. Let the user choose a radius within the configured maximum.
  5. Create the radar with POST /radars.
  6. Register push delivery with POST /onesignal/session if the app has not already registered the user’s device/session.
  7. Show the active radar until it is canceled, expires, or a vehicle notification is delivered.

Example request:

POST /radars
Content-Type: application/json

{
  "startTime": "2026-05-21T14:30:00+02:00",
  "position": {
    "type": "Point",
    "coordinates": [16.363449, 48.210033]
  },
  "radius": 1000
}

Example response:

{
  "id": 1234,
  "startTime": "2026-05-21T14:30:00+02:00",
  "endTime": "2026-05-21T15:30:00+02:00",
  "address": "Vienna, Austria",
  "position": {
    "type": "Point",
    "coordinates": [16.363449, 48.210033]
  },
  "radius": 1000
}

Show The Active Radar

Use GET /radars to show the user’s active radars. In normal app flows this is usually a single current radar because overlapping active windows are rejected.

GET /radars

Use the returned position and radius to draw the alert circle on the map. Use endTime to show how long the alert remains active.

Update Or Cancel A Radar

Use PATCH /radars/{radarId} to update the active radar’s time window or radius. The original position cannot be changed by the update flow, so create a new radar if the user wants to watch a different place.

Use DELETE /radars/{radarId} when the user turns off the alert. The API returns 204 No Content and the radar is canceled.

Notification Handling

When the backend finds an available free-floating vehicle inside the radar area, it sends a vehicle radar notification and marks the radar as delivered. The notification contains a rental deeplink placeholder so the app can open the vehicle or rental flow directly.

On notification open:

  1. Resolve the deeplink target.
  2. Re-read the vehicle with GET /vehicles/{id} before showing the detail sheet.
  3. Continue with the normal selected-vehicle flow: show pricing, applicable vouchers, rental requirements, and start/reserve actions.

Always re-read the vehicle because another user may have rented it between notification delivery and app open.

Most Relevant APIs

Area Endpoints
Vehicle discovery before radar GET /vehicles
Radar lifecycle GET /radars, POST /radars, GET /radars/{radarId}, PATCH /radars/{radarId}, DELETE /radars/{radarId}
Push/session delivery POST /onesignal/session
Vehicle detail after notification GET /vehicles/{id}, GET /vehicles/code/{code}

Implementation Notes