Fieldmotion API Getting started

Vehicles

Calculate a tracked vehicle ETA

POST /a/VehicleTracking_eta

Calculate and cache Webfleet travel time from one visible vehicle position to its next job.

When to use this endpoint

Use VehicleTracking_eta when a Fleet Operations user selects a visible tracked vehicle that has a future job with map coordinates.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session, and the tenant’s features2.vehicle_tracking entitlement must currently equal 1. The entitlement is read from the global account row on every call.

The user needs the explicit pageFleetOperations_view role permission for Fleet Operations. Client administrators satisfy the role check.

Parameters

ParameterTypeRequiredDescription
vehicle_idInteger-compatibleEffectively yesNumeric local vehicle ID. The current handler does not reject an omitted or zero value before building the fleet payload; always send a validated positive ID.

Example request

$eta = FM_api('VehicleTracking_eta', [
	'vehicle_id' => '30124',
]);

Example response

{
  "available": true,
  "reason": "",
  "vehicle_id": 30124,
  "job_id": 70124,
  "duration_seconds": 600,
  "distance_metres": 5000,
  "traffic_delay_seconds": 30,
  "arrival_at": 1790847000,
  "cached": false
}

Errors and unusual responses

ResponseCondition
{"error":"not logged in"}No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
{"available":false,"reason":"Vehicle Tracking is not connected"}No active connected provider exists.
{"available":false,"reason":"A current permitted vehicle position is unavailable"}The vehicle, mapping, position, visible privacy state, or coordinates are unavailable.
{"available":false,"reason":"The next job has no map coordinates"}There is no next job or its customer snapshot lacks latitude/longitude.
{"available":false,"reason":"ETA rate limit reached","retry_after":7}Another uncached route was claimed for the connection within the preceding ten seconds.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

  • The route targets the first future incomplete job assigned to an active user of the vehicle. It never sends job coordinates to the browser before the server-side route call.
  • A successful or unsuccessful provider route is cached for five minutes using vehicle position and destination coordinates as the key. A cache hit returns cached:true.
  • Uncached route calls are limited connection-wide to one every ten seconds. retry_after reports the remaining seconds.
  • Webfleet ISO-8601 or numeric duration fields are normalised to seconds. A zero/invalid duration returns available:false with Webfleet did not return an ETA but still includes route fields.

Side effects

  • For an uncached eligible request, decrypts stored credentials, claims the connection’s route-rate timestamp, calls Webfleet calcRouteSimpleExtern, and stores a connection-wide route cache for five minutes.

See it in Fieldmotion

CRM1

No CRM1 production caller was found. Vehicle Tracking navigation and screens are implemented in CRM2.

CRM2

Open Jobs → Fleet Operations and select a map-enabled vehicle card that has a next job. The UI requests ETA and displays rounded-up minutes.

Related endpoints