Calculate ETE ETA (for an Ocean Shipment)

Use project44's Unified Tracking API to return an estimated time of arrival (ETA) for any stops in a shipment’s journey. During the Create a Shipment or Update a Shipment workflows, include the location information (city, state, country, and postal code) for any stop you want to calculate an ETA for. This includes stops project44 is not tracking (like a drayage move), stops in a different leg of the shipment journey, or a final destination.

Why Use ETE ETA?

• Get automatic ETA updates when a shipment is delayed.
• Get an ETA for any stop in shipment’s journey - including current or future route segments.

Overview of Workflow

To get ETE ETAs for a shipment,

1. Submit the necessary stop information during the Create a Shipment or Update a Shipment workflows.
2. Retrieve the stop ETA data with a pull request using the Get Event History response or Get Full Tracking History response. If you have created a webhook, you will receive stop ETA data in the push tracking notification.

Submit Stop Information to Calculate ETE ETA

To receive an ETA, you must submit location information for any stop you want an ETA calculated. This can be done through the Create a Shipment or Update a Shipment workflows.

Requirements

• Required information to create or update a shipment
• Stop location information
  • City
  • State
  • Country
  • Postal Code

Workflow

1. Using the endpoint in the Create a Shipment or Update a Shipment workflows, prepare a POST or PUT request to /api/v4/shipments/tracking.

2. Add the location information for any the stop(s) you want an ETA calculated for in the routeInfo.stops array. For example,

{
  "id": "string",
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "string"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "string"
    }
  ],
  "routeInfo": {
    "stops": [
      {
        "type": "UNKNOWN",
        "location": {
          "id": "string",
          "name": "string",
          "address": {
            "postalCode": "string",
            "addressLines": [
              "string"
            ],
            "city": "string",
            "state": "string",
            "country": "US"
          },
          "coordinates": {
            "latitude": 0,
            "longitude": 0
          }
        }
      }
    ]
  }
}

::: note This only shows the minimum required request schema to create a shipment and calculate stop ETAs. To update a shipment with stop location information to calculate stop ETAs, include the shipments id returned in the POST Create a Shipment response. For the full request schema and descriptions for all fields and objects, please see our reference documentation. :::

3. Send the request.

Expected System Response

You have successfully submitted the response when you receive a 200 OK response.

It will take time for the source data to return stop ETA information. When data is available, you can find the ETA for a stop in events.estimateDateTime. The event type for a stop with an ETA will be ARRIVAL_AT_STOP.

Here is an sample of the minimum response schema:

{
  "id": "93294f58-f87a-48e0-9f68-7d3f6e0aaa2f",
  "identifiers": [
    {
      "type": "BILL_OF_LADING",
      "value": "string"
    },
    {
      "type": "CARRIER_SCAC",
      "value": "string"
    }
  ],
  "routeInfo": {
    "stops": [
      {
        "type": "UNKNOWN",
        "location": {
          "id": "string",
          "name": "string",
          "address": {
            "postalCode": "string",
            "addressLines": [
              "string"
            ],
            "city": "string",
            "state": "string",
            "country": "US"
          },
          "coordinates": {
            "latitude": 0,
            "longitude": 0
          }
        }
      }
    ]
  },
  "events": [
    {
      "dateTime": "string",
      "receivedDateTime": "string",
      "type": "DEPARTURE_FROM_STOP",
      "description": "string",
      "stopId": "string",
      "routeSegmentId": "string",
      "estimateDateTime": "string",
      "estimateLastCalculatedDateTime": "string",
      "plannedDateTime": "string",
      "plannedEndDateTime": "string"
    },
    {
      "receivedDateTime": "string",
      "type": "ARRIVAL_AT_STOP",
      "stopId": "string",
      "estimateDateTime": "string"
    }
  ]
}

If you do not want to wait for the data source to return information, submit the following information for the event in addition to the information above.

{
  "type": "ARRIVAL_AT_STOP",
  "stopId": "99f6b915-c65b-4e1c-90e7-a6b12ec5ed88",
  "plannedDateTime": "string"
}

Instead of the plannedDateTime field, you can specify for any other time field including the dateTime field or the estimateDateTime field.

Retrieve Stop ETA

Use either the Get Event History workflow or Get Full Tracking History workflow to retrieve the ETA for a stop. If you have created a webhook, you will receive stop ETA data in the push tracking notification.

Requirements

• Required information to create or update a shipment

Workflow

1. Use the endpoint in either the Get Event History workflow or Get Full Tracking History workflow.

2. Send the request.

Expected System Response

You have successfully submitted the response when you receive a 200 OK response.

It will take time for the source data to return stop ETA information. When data is available, you can find the ETA for a stop in events.estimateDateTime. The event type for a stop with an ETA will be ARRIVAL_AT_STOP.

{
  "events": [
    {
      "receivedDateTime": "2022-11-06T05:44:00+0000",
      "type": "ARRIVAL_AT_STOP",
      "stopId": "8adef901-06af-3d43-b4e4-4b53bc1f7db4",
      "estimateDateTime": "2022-11-14T10:00:00+0000"
    }
  ]
}