Live Geo Tracking
During the last mile of the delivery, the recipient can be provided with a real-time update of the current progress of their delivery through parcelLab's live geo tracking.
Overview
Our live geo tracking aims to provide the recipient with a detailed status update of their delivery during the last mile (that is: when goods have been loaded onto the delivery truck and are on their way to the recipient).
The information contained in a status update is described in the following table.
Current location of delivery truck
Geo coordinates as Latitude and Longitude.
Progress of tour in number of stops
How many stops/deliveries will be done by the delivery truck before arriving at the recipient's location.
Estimated time of delivery
If available, the current estimated time or time window of delivery.
For parcelLab to provide this information to the recipient, you need to provide the following independent sets of data to us:
Tour plan — which order will be served by which delivery truck or tour.
Geo coordinates — the geo coordinates describe the current location of a
tour.
Tour Plan and Progress
A tour references an individual delivery tour performed by a truck on a given day. These individual stops are defined in the tour plan.
The information contained in a tour plan is described in the following table.
TourID
A unique identifier of the tour. This can be any alphanumeric value. If the carrier's systems do not explicitly hold that value, it could be the current date and license plate of the truck.
Note: This value will not be exposed to the recipient and is only for internal reference.
Stops
The list of stops of the tour, each stop holds the following values:
Shipment- the shipment identifier (for example: barcode, order number, tracking number of this specific stop) (String, required).TourOrder- the number of the stop on the tour (Number, required).EstimatedDeliveryTime- the estimated time of arrival (HH:mm, optional).Status- the status of the stop on the tour, which can be eitherOpen(not yet fulfilled) orClosed(already fulfilled, or cancelled/skipped).
You can transfer the tour plan to parcelLab in one of the following ways:
Implicitly - you will not explicitly send us the tour plan, but rather associate the individual orders with a tour by extending the scans and status events sent.
Explicitly - you send (and consequently) update the tour plan.
Send Status with Tour Information
Details of how the courier/events endpoint can be used to update the status of an individual delivery while also providing information about the tour and thus implicitly sending us the tour plan are described below.
A status update with tour information can be transmitted as shown below in the .json and .xml examples. The payload can alternatively be sent as a file via SFTP.
It extends every event with the following keys:
TourId- the unique identifier of the tour.TourOrder- the numerical ordering position of this specific order on this tour (for example: a1for the first stop on the tour).
{
"Events": [
{
"Shipment": "1000002",
"Timestamp": "2020-01-01 12:30:00.000+01:00",
"Location": "Berlin",
"StatusCode": "OutForDelivery",
"TourId": "TOUR-X1D7CU89",
"TourOrder": 1
},
{
"Shipment": "DTRAXZYYY3",
"Timestamp": "2020-01-01 10:00:00.000+01:00",
"Location": "Depot Berlin",
"StatusCode": "Scheduled",
"Details": {
"EstimatedDeliveryDate": "2020-01-08",
"EstimatedDeliveryTimeFrom": "11:00",
"EstimatedDeliveryTimeTo": "14:00"
},
"TourId": "TOUR-X1D7CU89",
"TourOrder": 2
}
]
}Send a Tour Plan
Details of how the courier/tour/plans endpoint can be used to send a tour plan are described below.
A tour plan requires a TourId and a list of Stops.
The stops can have the keys described in the following table.
Shipment
The unique identifier of the Shipment, as given in status updates.
Required
TourOrder
The numerical ordering of this stop on the whole tour.
Required
EstimatedDeliveryTime
A current estimate of the time of arrival at this stop.
Optional
Status
The current status of this stop (that is: Open as long as not reached yet, and Closed after stop has been delivered or cancelled or skipped).
Required
A tour plan can be transmitted as shown below in the .json and .xml examples.
curl -X POST \
https://api.parcellab.com/courier/tour/plans \
-H 'Content-Type: application/json' \
-H 'token: this-is-a-secure-token-issues-by-parcelLab' \
-d '{
"TourPlans": [
{
"TourId": "TOUR-X1D7CU89",
"Stops": [
{
"Shipment": "1000002",
"TourOrder": 1,
"EstimatedDeliveryTime": "13:30",
"Status": "Closed"
},
{
"Shipment": "DTRAXZYYY3",
"TourOrder": 2,
"Status": "Open"
}
]
}
]
}'A tour plan can alternatively be sent as a .xml file via SFTP.
<TourPlans>
<TourPlan>
<TourId>TOUR-X1D7CU89</TourId>
<Stops>
<Stop>
<Shipment>1000002</Shipment>
<TourOrder>1</TourOrder>
<EstimatedDeliveryTime>13:30</EstimatedDeliveryTime>
<Status>Closed</Status>
</Stop>
<Stop>
<Shipment>DTRAXZYYY3</Shipment>
<TourOrder>2</TourOrder>
<Status>Open</Status>
</Stop>
</Stops>
</TourPlan>
</TourPlans>Geo Coordinates
After the tour plan has been transferred to parcelLab, you can send us the geo coordinates.
The data model for geo coordinates holds the keys described in the following table.
TourId
The unique identifier of the delivery tour as given with the tour plan.
String
Timestamp
The timestamp of the location data formatted as YYYY-MM-DD HH:mm:ss+-HH:mm.
Datetime
Latitude
The GPS position's latitude given as float (for example: 48.1365628).
Number
Longitude
The GPS position's longitude given as float (for example: 11.5588959).
Number
Send Geo Coordinates
Details of how the courier/tour/coordinates endpoint can be used to send the geo coordinates of a tour are described below.
Geo coordinates can be transmitted using this API call via cURL as shown below in the .json and .xml examples.
curl -X POST \
https://api.parcellab.com/courier/tour/coordinates \
-H 'Content-Type: application/json' \
-H 'token: this-is-a-secure-token-issues-by-parcelLab' \
-d '{
"GeoCoordinates": [
{
"TourId": "TOUR-X1D7CU89",
"Timestamp": "2020-01-01 16:12:00.000+01:00",
"Latitude": 48.1365628,
"Longitude": 11.5588959
}
]
}'Geo coordinates can alternatively be sent as a .xml file via SFTP.
<?xml version=1.0 encoding=UTF-8?>
<GeoCoordinates>
<GeoCoordinate>
<TourId>TOUR-X1D7CU89</TourId>
<Timestamp>2020-01-01 16:12:00.000+01:00</Timestamp>
<Latitude>48.1365628</Latitude>
<Longitude>11.5588959</Longitude>
</GeoCoordinate>
</GeoCoordinates>Last updated
Was this helpful?