Get the current vehicle position by name
The method returns the vehicle’s latest stored position. The vehicle is identified by its exact name in PILOT.
The method is intended for integration with shipment tracking systems, including WIMT. Unlike methods that use an IMEI, this method accepts the vehicle name in the truckNo parameter.
An interactive description of the method is available in Swagger — Track and Trace.
How to get data
Method
POST
Request address
https://<server_address>/api/v3/vehicles/track-and-trace
Replace <server_address> with the PILOT server address.
Authorization
The request uses standard API V3 authorization with a Bearer token.
Pass the token in the Authorization header:
Authorization: Bearer <access_token>
Replace <access_token> with a valid API V3 access token.
Request headers
|
Header
|
Required
|
Description
|
|
Authorization
|
Yes
|
Bearer token used to authorize the API V3 user
|
|
X-Node
|
Yes
|
The user’s node number. It is used to route the request to the correct server
|
|
Content-Type
|
Yes
|
The request body format. Specify application/json
|
|
Accept
|
No
|
The response format. The recommended value is application/json
|
Example headers:
Authorization: Bearer <access_token>
X-Node: 3
Content-Type: application/json
Accept: application/json
Request parameters
The parameters are passed in the request body in JSON format.
|
Parameter
|
Type
|
Required
|
Description
|
|
shipmentNo
|
String
|
Yes
|
The shipment or consignment number. The method accepts the value but does not store or return it
|
|
truckNo
|
String
|
Yes
|
The vehicle name in PILOT. It must exactly match the vehiclenumber value
|
|
countryID
|
String
|
Yes
|
The country code, for example ZA. It is returned unchanged in the response
|
|
trackingFlag
|
String
|
Yes
|
The tracking status, for example START or STOP. In the current version, the value is accepted but is not stored and does not affect request processing
|
Vehicle lookup
The method searches for an exact truckNo match among the vehicles available to the authenticated user.
The value must exactly match the vehicle name—the vehiclenumber value—in PILOT. The lookup takes letter case, spaces, and special characters into account.
For example, if the vehicle name is KS51YPGP_F, pass the following value:
"truckNo": "KS51YPGP_F"
|
If the name does not match or the user does not have access to the vehicle, the method does not return its position.
Example request
{
"shipmentNo": "SHIPMENT-123",
"truckNo": "KS51YPGP_F",
"countryID": "ZA",
"trackingFlag": "START"
}
|
Example cURL request:
curl --request POST \
--url "https://<server_address>/api/v3/vehicles/track-and-trace" \
--header "Authorization: Bearer <access_token>" \
--header "X-Node: 3" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
"shipmentNo": "SHIPMENT-123",
"truckNo": "KS51YPGP_F",
"countryID": "ZA",
"trackingFlag": "START"
}'
|
Response
If the request is successful, the method returns the vehicle’s latest stored GPS position, address, time zone, and account name.
|
Field
|
Type
|
Description
|
|
code
|
Integer
|
The request result code. A value of 0 indicates that the request was successful
|
|
msg
|
String
|
The request result. A successful request returns OK
|
|
process_time
|
Number
|
The request processing time in seconds
|
|
countryID
|
String
|
The country code received in the request. It is returned unchanged
|
|
timeZone
|
String
|
The IANA time zone identifier, for example Africa/Johannesburg
|
|
truckNo
|
String
|
The name of the vehicle found in PILOT
|
|
latitude
|
Number
|
The latitude of the latest stored GPS position
|
|
longitude
|
Number
|
The longitude of the latest stored GPS position
|
|
source
|
String
|
The name of the account to which the vehicle belongs
|
|
streetName
|
String
|
The address of the latest position obtained through reverse geocoding
|
|
lastRecordedOn
|
Integer
|
The time when the latest GPS position was recorded, as a Unix timestamp
|
The response does not include shipmentNo, trackingFlag, or trackLink.
Example successful response
{
"code": 0,
"msg": "OK",
"process_time": 0.001,
"countryID": "ZA",
"timeZone": "Africa/Johannesburg",
"truckNo": "KS51YPGP_F",
"latitude": -26.2041,
"longitude": 28.0473,
"source": "Example Fleet",
"streetName": "Main Road, Johannesburg",
"lastRecordedOn": 1785142800
}
|
Time formats
Time zone
The timeZone field contains an IANA time zone identifier:
"timeZone": "Africa/Johannesburg"
|
The IANA identifier defines a regional time zone and allows its applicable rules to be handled correctly.
The method does not return a fixed UTC offset such as UTC+02:00.
Time of the latest position
The lastRecordedOn field contains the time of the latest GPS position as a Unix timestamp:
"lastRecordedOn": 1785142800
|
A Unix timestamp is the number of seconds elapsed since January 1, 1970, at 00:00:00 UTC. It does not depend on a time zone.
To display the date and time to the user, convert lastRecordedOn using the time zone specified in timeZone.
Address determination
The streetName field is generated using reverse geocoding: PILOT converts the coordinates of the latest position into a text address.
"streetName": "Main Road, Johannesburg"
|
The completeness and accuracy of the address depend on the available mapping data.