Vehicle position
Permission:
create_vehicle_positions
A vehicle position stores the recorded location of a vehicle. Positions from ioki Vehicle App are queued and processed asynchronously, so the recorded time can differ from the time when ioki Platform saves the position.
Create a new vehicle position
To add a position manually in Control Center, select ⚙️ > Add new position for the relevant vehicle.
Manual positions use the same update rules as positions from ioki Vehicle App.
Each vehicle position can contain the following values.
- Vehicle. The vehicle that the position belongs to.
- Lat / Lng. Latitude and longitude.
- Recorded at. The time when the position was recorded, not when it was stored in ioki Platform.
- Accuracy. Optional accuracy value.
- Speed. Optional speed in m/s.
- Heading. Optional heading in degrees.
- Altitude accuracy. Optional altitude accuracy in m.
- Altitude. Optional altitude in m.
- Source. Optional source value.
Check when a position update is processed
Because many updates can arrive in a short time, ioki Platform only processes a new position when at least one of the following applies:
- there is no current tracked position yet
- the new position differs by at least 50 meters
- the recorded time differs by at least 5 seconds
- the update can trigger pickup approached, pickup reached, or drop-off reached logic for an active task
If both the time difference and the distance difference stay below those thresholds, the update is ignored.
On top of this, not every processed position update sends a webhook. Position update webhooks are sampled: roughly 30 percent of processed updates, about one in three, send one. This sampling reduces webhook volume and applies only to the position update webhook, not to other webhook events. Integrators should not expect one webhook per position update.
Check approached and reached states
The system compares the position with the calculated point of the active pickup or drop-off task.
| State | Threshold |
|---|---|
| Pickup approached | Under 500 meters and under 10 minutes before the calculated pickup time |
| Pickup reached | Under 50 meters and under 5 minutes before the calculated pickup time |
| Drop-off approached | Under 500 meters and under 2 minutes before the calculated drop-off time |
| Drop-off reached | Under 50 meters and under 5 minutes before the calculated drop-off time |
When one of these states is reached, the related ride is updated. Passengers are notified when the vehicle approaches pickup, reaches pickup, or approaches drop-off. Reaching drop-off updates the ride but does not send a passenger notification at that step.
Check off-route recalculation
If a processed update marks the vehicle as off route, ioki Platform can trigger a task-list recalculation for the active vehicle planning. This is limited to once every 25 seconds per active task list.
Check the current position
The current position is the newest vehicle position that:
- was recorded within the last 10 minutes
- has an accuracy value below 100 meters
Positions with an accuracy of 100 meters or more, or without an accuracy value, are not used as the current position.
How long positions are kept
Vehicle positions are kept for 28 days. After that, they are pruned and are no longer available, for example on the map of an older ride.