Tracking Reference


Stay up-to-date on the progress of your shipments by tracking them from the moment you've booked with a transporter until the shipment reaches its destination. Also see the transitStatus field on GET https://api.uship.com/v2/listings/ doc to retrieve listings of a particular user type with specific transit status(es).

Table of Contents

Tracking History

Update Tracking

Tracking History

GET

URI https://api.uship.com/v2/listings/{listingId}/transitStatuses
  • The listingId must belong to a booked listing.
  • Valid for the Lister or the winning Bidder for the booked listing.
  • Retrieve the location history of the tracking recorded for the booked listing.
  • The most recent reported location for a Service Provider (for their booked listing) returns when available.

We track the punctuality of a shipment to encourage Service Providers to pick up and deliver on time. A shipment is considered on time when...

  • the pick up occurs before the latest pick up time on the bid.
  • the delivery occurs before the latest delivery time on the bid.

 

Response

Success Status: 200 OK

Example

GET https://api.uship.com/v2/listings/{listingId}/transitStatuses

{
    "mostRecentLocation": {
        "status": "Delivered",
        "punctuality": {
            "value": "OnTime",
            "label": "On time",
            "shortLabel": "On time"
        },
        "recorded": "2014-10-15T21:34:50Z",
        "latitude": 57.990833,
        "longitude": -68.463611
    },
    "totalCount": 4,
    "items": [
        {
            "status": "ReadyForDispatch",
            "punctuality": {
                "value": "NotApplicable",
                "label": "Not Applicable",
                "shortLabel": "n/a"
            },
            "recorded": "2014-10-15T21:30:23Z"
        },
        {
            "status": "Dispatched",
            "punctuality": {
                "value": "NotApplicable",
                "label": "Not Applicable",
                "shortLabel": "n/a"
            },
            "recorded": "2014-10-15T21:34:23Z",
            "latitude": 55.990833,
            "longitude": -66.463611
        },
        {
            "status": "PickedUp",
            "punctuality": {
                "value": "OnTime",
                "label": "On time",
                "shortLabel": "On time"
            },
            "recorded": "2014-08-07T21:34:42Z",
            "latitude": 56.990833,
            "longitude": -67.463611
        },
        {
            "status": "Delivered",
            "punctuality": {
                "value": "OnTime",
                "label": "On time",
                "shortLabel": "On time"
            },
            "recorded": "2014-10-15T21:34:50Z",
            "latitude": 57.990833,
            "longitude": -68.463611
        }
    ]
}

 

Reference

totalCount

Integer for the number of items in the history

mostRecentLocation Object
Field Type Description
status String The status of the shipment paired with the most recent location information. Returns ReadyForDispatch, Dispatched, PickedUp, or Delivered.
punctuality Container

Wrapper for the fields that describe whether or not the transit status occurred on time. This property corresponds only to the status of this object.

Values

  • "NotApplicable" returns for ReadyForDispatch and Dispatched
  • "OnTime" returns for PickedUp and Delivered when the status is set before the latest pick up/delivery time.
  • "NotOnTime" returns for PickedUp and Delivered when the status is set after the latest pick up/delivery time.

The label is localized for the value. The shortLabel is the localized value for a mobile or touch screen device.

recorded String The latest date and time (UTC) reported by the device.
longitude Decimal The last report of the location longitude in decimal degrees.
latitude
Decimal The last report of the location latitude in decimal degrees.
items Object
Field Type Description
status String

The information associated with the new transit status. Returns ReadyForDispatch, Dispatched, PickedUp, and Delivered. This field is not included with updates that do not represent a transit status change.

punctuality Container

Wrapper for the fields that describe whether or not the transit status update occurred on time. This property corresponds only to the status of this object.

Values

  • "NotApplicable" returns for ReadyForDispatch and Dispatched
  • "OnTime" returns for PickedUp and Delivered when the status is set before the latest pick up/delivery time.
  • "NotOnTime" returns for PickedUp and Delivered when the status is set after the latest pick up/delivery time.

The label is localized for the value. The shortLabel is the localized value for a mobile or touch screen device.

 

recorded String The date and time (UTC) the transit status was reported by the device.
latitude Decimal Returns only when available. Report of the location latitude in decimal degrees.
longitude Decimal Returns only when available. Report of the location longitude in decimal degrees.
comment String If a Service Provider provided additional information, the message will return in this field.

 

Transit Statuses

These statuses will only appear for a booked listing that has an accepted bid. 

Service Providers use shipment statuses to give customers visibility into the current state of the shipment. Notifications will be sent to customers upon a status change.

Value Label Description
ReadyForDispatch
Booked The shipment has been matched with a Service Provider. The booked listing state where the Service Provider has not yet dispatched the shipment.
Dispatched
Dispatched The Service Provider has started on the route to pick up the shipment.
PickedUp
PickedUp The Service Provider has loaded the shipment onto their vehicle and is en route to the delivery location.
Delivered
Delivered The Service Provider has delivered the shipment to the approved recipient at the delivery location.

 

Hypermedia Link

The following transit status related hypermedia link is available when retrieving listings via GET https://api.uship.com/listings/{listingId}.

{
  "rel": "Item",
  "verb": "GET",
  "href": "/v2/listings/{listingId}/transitStatuses",
  "title": "transitStatuses"
}

For information on Hypermedia Links in the uShip API, visit https://developer.uship.com/docs/read/Hypermedia_Links.

 

Error Messages

Error Code: 403 You are not allowed to perform the action you are attempting

Description
Transit Statuses are only visible when there is an accepted bid.

"You do not have permission to view this listing's transit status history" - This message will occur for any user other than the owner of the booked listing and the winning bidder on a listing that is in any status before it is booked.

 

Update Tracking

 

POST


https://api.uship.com/v2/listings/{listingId}/dispatched

https://api.uship.com/v2/listings/{listingId}/pickedup

https://api.uship.com/v2/listings/{listingId}/delivered

 

Workflow

The workflow is forward only so that a service provider may only update their status from dispatched to picked up to delivered. However, a service provider can skip statuses as depicted in this table of possibilities.

Possible combinations

Possibility Status 1    >> Status 2    >> Status 3
1 delivered - -
2 dispatched delivered -
3 picked up delivered -
4 dispatched picked up delivered

Request

Submit an empty input body for these endpoints. 

Response

Status code: 201 Created

Response Header

Location header

https://api.uship.com/v2/listings/{listingId}/