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.
These will be referenced from now on as a tour (that is: the delivery tour of a specific delivery truck on a given day). The tour plan associates individual deliveries within a given order with a 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.
Choose the transfer method that works better with your system. Both versions are covered in this documentation.
Send Status with Tour Information
Details of how the webhook/{courier}/ 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.
POST Send Status with Tour Information
You can update the status of a delivery while providing information about the tour and therefore implicitly send us the tour plan using the webhook/{courier}/ endpoint (that is: this endpoint would be called on a specific status or scan event).
This endpoint allows you to update the status of an individual delivery while also providing information about the tour and thus implicitly send us the tour plan (that is: this endpoint would be called on a specific status or scan event).
The details of the Send Status with Tour Information API are described in this section.
API Details
POST https://webhooks-api.parcellab.com/webhook/{courier}/
Header
content-type
string
'application/json'
Request Body
Events
array
JSON as described below
Responses
202 - accepted
400 - if data is ill formatted, the response will describe the issue with the payload (for example:
Invalid events, every "Event" needs a key "Shipment")401 - if no or an invalid token is provided
A status update with tour information can be transmitted as shown below in the .json example. The payload can alternatively be sent as a file via SFTP.
For further details on file transfers, see how you can send files to parcelLab.
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).
Send a Tour Plan
Details of how the webhook/{courier}/tour_plans endpoint can be used to send a tour plan are described below.
POST Send a Tour Plan
You can explicitly send us the tour plan (that is: the stops for a planned tour) using the webhook/{courier}/tour_plans endpoint.
The details of the Send a Tour Plan API are described in this section.
API Details
POST https://webhooks-api.parcellab.com/webhook/{courier}/tour_plans
Header
content-type
string
'application/json'
Request Body
TourPlans
array
List of tour plans as described below
Responses
202 - accepted
400 - an error description for incorrectly formatted payloads (for example:
Invalid stops on tour plan XYZ, some keys not allowed)401 - if no or an invalid token is provided
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 example.
A tour plan can alternatively be sent as a .xml file via SFTP.
For further details on file transfers, see how you can send files to parcelLab.
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
Geo coordinates can be transferred in any accuracy, as they will be automatically obfuscated in accordance with local data privacy laws when showing them to the recipient.
Send Geo Coordinates
Details of how the webhook/{courier}/coordinates endpoint can be used to send the geo coordinates of a tour are described below.
POST Send Geo Coordinates
You can send us the geo coordinates of a tour using the webhook/{courier}/coordinates endpoint.
The details of the Send Geo Coordinates API are described in this section.
API Details
POST https://webhooks-api.parcellab.com/webhook/{courier}/coordinates
Header
content-type
string
'application/json'
Request Body
geoCoordinates
array
JSON as described below
Responses
202 - accepted
400 - an error description for incorrectly formatted payloads (for example:
Invalid stops on tour plan XYZ, some keys not allowed)401 - if no or an invalid token is provided
Geo coordinates can be transmitted using this API call via cURL as shown below in the .json example.
Geo coordinates can alternatively be sent as a .xml file via SFTP.
For further details on file transfers, see how you can send files to parcelLab.
Last updated
Was this helpful?