Last updated

Get Shipment Information

Get tracking updates for your Rail shipment. A shipment must be created and added to project44's network before we can return tracking information. If you have not done so, please Create a Shipment. project44 offers four targeted endpoints for returning shipment tracking information. This allows you to fetch the specific information you need when you need it.

  • Use the Get Event History endpoint to return shipment events, or milestones.
  • Use the Get Position History endpoint to return shipment positions.
  • Use the Get Route Information endpoint to return only route segment and stop information for a shipment.
  • Use the Get Tracking History endpoint to return all shipment tracking information including events, positions, stop information, and route segment information.

Our Shipment Tracking APIs are designed to be used in an asynchronous manner. This means that a behavior or functionality may not be immediately available upon submission to our API because our system processes data asynchronously.

For more information about how to use the specific endpoints and features, please consult our user guide and API Reference documentation.

After the shipment has been created, project44 will discover related shipments and return their information in the relatedShipments array in the GET responses. Related shipments will not be identified immediately after creation. If you want to see the related shipments immediately after shipment creation, you will need to include the related shipment identifier information in the identifiers array of the shipment creation endpoint.

Get Event History

Get information about shipment milestones (events) that have occurred and are planned to occur.

Requirements

  • project44-generated Shipment ID (the id returned in the 200 OK response during Shipment Creation)

Workflow

  1. Prepare a GET request to /api/v4/shipments/{shipmentId}/eventhistory and include the Master Shipment ID. For example: GET /api/v4/shipments/93294f58-f87a-48e0-9f68-7d3f6e0aaa2f/eventhistory.

    To return stop information in the response, include the includeRouteInfo query parameter in your request. For example, GET /api/v4/shipments/93294f58-f87a-48e0-9f68-7d3f6e0aaa2f/eventhistory?includeRouteInfo=true

    Arguments

    NameTypeDescriptionNotes
    shipmentIdstringPath Parameter. The project44-generated id returned in the 200 OK response during Shipment Creation.This field is required.
    includeRouteInfobooleanQuery paramter. Include to return stop information for the shipment.This field is optional. Default value: false

  2. Send the request.

Expected System Response

The request is successfully submitted and confirmed when a 200 OK response is received.

JSON
{
    "shipment": {
        "id": "string",
        "identifiers": [
            {
                "type": "CONTAINER_ID",
                "value": "string"
            }
        ],
        "routeInfo": {},
        "relatedShipments": []
    },
    "states": [
        {
            "type": "IN_TRANSIT",
            "startDateTime": "2023-01-05T04:00:00+0000",
            "endDateTime": "2023-01-10T04:00:00+0000",
            "stopId": "string"
        },
        {
            "type": "AT_STOP",
            "startDateTime": "2023-01-10T04:00:00+0000",
            "endDateTime": "2023-01-13T06:29:00+0000",
            "stopId": "string"
        },
        {
            "type": "IN_TRANSIT",
            "startDateTime": "2023-01-13T06:29:00+0000",
            "stopId": "string"
        }
    ],
    "events": [
        {
            "dateTime": "2023-01-05T04:00:00+0000",
            "receivedDateTime": "2023-02-08T07:40:00+0000",
            "type": "TRACKING_START",
            "stopId": "string"
        },
        {
            "dateTime": "2023-01-10T04:00:00+0000",
            "receivedDateTime": "2023-02-08T07:40:00+0000",
            "type": "TRACKING_INITIATE",
            "stopId": "string"
        },
        {
            "dateTime": "2023-01-13T04:00:00+0000",
            "receivedDateTime": "2023-02-08T07:40:00+0000",
            "type": "LOAD_ONTO_VEHICLE",
            "stopId": "f5d0d694-995f-307c-9e11-a42118f71d64",
            "plannedDateTime": "string"
        },
        {
            "dateTime": "2023-01-13T06:29:00+0000",
            "receivedDateTime": "2023-02-08T07:40:00+0000",
            "type": "DEPARTURE_FROM_STOP",
            "stopId": "string"
        },
        {
            "receivedDateTime": "2023-02-08T07:40:00+0000",
            "type": "ARRIVAL_AT_STOP",
            "stopId": "string",
            "estimateDateTime": "2023-02-14T01:00:01+0000",
            "estimateLastCalculatedDateTime": "2023-02-08T11:41:18+0000",
            "plannedDateTime": "2023-02-12T20:00:00+0000"
        },
        {
            "receivedDateTime": "2023-02-08T07:40:00+0000",
            "type": "UNLOAD_FROM_VEHICLE",
            "stopId": "string",
            "estimateDateTime": "2023-02-15T19:55:00+0000",
            "estimateLastCalculatedDateTime": "2023-02-08T11:41:18+0000"
        },
        {
            "receivedDateTime": "2023-02-08T07:40:00+0000",
            "type": "TRACKING_COMPLETE",
            "stopId": "string",
            "plannedDateTime": "2023-02-12T20:00:00+0000"
        }
    ]
}

This is an example of what could be returned in the response. Null fields will not show up in the response. Please refer to the API Reference documentation for more information on required and potential null fields.

See the Appendix for descriptions of the Rail Shipment Event Types, Rail Shipment State Types, and Rail Shipment Stop Types returned by this endpoint.

Fields and Objects

| Field | Type | Description | Notes | | --- | --- | --- | --- | --- | | id | string | The Master Shipment ID of the shipment. | This field is returned in the 200 OK response during shipment creation. | | | identifiers | string | The shipment identifier. This is different from the master shipment id (id). | The shipment ID is necessary for getting tracking information, updating a shipment, and deleting a shipments. | | identifiers.type | string | The shipment identifier type. |

Valid EU values: WAGON_ID, TRAIN_NUMBER

Valid NA values: CONTAINER_ID, TRAILER_ID, RAIL_CAR_ID, BILL_OF_LADING, WAYBILL

| | identifiers.value | string | The shipment identifier value. | | | routeInfo | object | An object of the shipment's route information. | | | relatedShipments | array of objects | An array of all containers tracked under the overall shipment (as created by the user) is returned in the relatedShipments object. | Each object uses an unique ID (id) to retrieve or identify (for PUSH) updates related to the designated container. | | states | array of objects | An array of all states the shipment was or currently is in. | | | states.type | string | The specific type of state the shipment was in. | See the Rail Shipment State Types in the Appendix for a full list of the supported state types and their descriptions. | | states.startDateTime | string | The time this state began. | This will be returned in UTC. | | states.endDateTime | string | The time that this state ended. May not be populated if the shipment is still in this state. This will be returned in UTC. | | states.stopId | string | The ID of the related stop.routeSegmentId: the route segment ID this state occurred along. | | | events | array of objects | An array of all events related to the shipment. | | | events.dateTime | string | The time at which the event took place (actual). | This will be returned in UTC. | | events.receivedDateTime | string | The last time information about event was modified. | | | events.type | string | The type of event that occurs. | See the Rail Shipment Event Types table in the Appendix for a full list of supported event types and descriptions. | | events.stopId | string | The project44 ID of the stop the event is related to. | | | events.estimateDateTime | string | project44’s latest estimated time for the event. | This will be returned in UTC. | | events.estimatedLastCalculatedDateTime | string | The last time the estimate date time was modified. | This will be returned in UTC. | | events.plannedDateTime | string | The carrier’s latest scheduled time for the event. |

Timestamps related to an event do not currently include contracted time or initial planned time by carrier.

This will be returned in UTC.

|

Errors

If there was a problem with your request, you will receive one of the following error codes

  • 400 Invalid request
  • 401 Invalid or missing credentials
  • 403 User not authorized to perform this operation

See the Error Response Codes section in the in the Appendix for more information on the meaning of these error codes.

Get Position History

Get information about a shipment's position history.

Requirements

  • project44-generated Shipment ID (the id returned in the 200 OK response during Shipment Creation)

Workflow

  1. Prepare a GET request to /api/v4/shipments/{shipmentId}/positionhistory using the shipment ID. For example, GET /api/v4/shipments/3294f58-f87a-48e0-9f68-7d3f6e0aaa2f/positionhistory.

    To return stop information in the response, include the includeRouteInfo query parameter in your request. For example, GET /api/v4/shipments/sample-p44-id-11111/positionhistory?includeRouteInfo=true

    Arguments

    NameTypeDescriptionNotes
    shipmentIdstringPath Parameter. The project44-generated id returned in the 200 OK response during Shipment Creation.This field is required.
    includeRouteInfobooleanQuery paramter. Include to return stop information for the shipment.This field is optional. Default value: false

  2. Send the request.

Expected System Response

You have successfully submitted the request when you receive a 200 OK response. Here is a sample of the response schema:

JSON
{
  "shipment": {
      "id": "string",
      "identifiers": [
          {
              "type": "CONTAINER_ID",
              "value": "string"
          }
      ],
      "routeInfo": {},
      "relatedShipments": []
  },
  "positions": [
    {
      "dateTime": "string",
      "receivedDateTime": "string",
      "routeSegmentId": "string",
      "latitude": 0,
      "longitude": 0
    }
  ]
}

This is an example of what could be returned in the response. Null fields will not show up in the response. Please refer to the API Reference documentation for more information on required and potential null fields.

See the Appendix for descriptions of the Rail Shipment Stop Types and Route Segment Identifiers.

Fields and Objects

| Field | Type | Description | Notes | | --- | --- | --- | --- | --- | | id | string | The Master Shipment ID of the shipment. | This field is returned in the 200 OK response during shipment creation. | | | identifiers | string | The shipment identifier. This is different from the master shipment id (id). | The shipment ID is necessary for getting tracking information, updating a shipment, and deleting a shipments. | | identifiers.type | string | The shipment identifier type. |

Valid EU values: WAGON_ID, TRAIN_NUMBER

Valid NA values: CONTAINER_ID, TRAILER_ID, RAIL_CAR_ID, BILL_OF_LADING, WAYBILL

| | identifiers.value | string | The shipment identifier value. | | | routeInfo | object | An object of the shipment's route information. | | | relatedShipments | array of objects | An array of all containers tracked under the overall shipment (as created by the user) is returned in the relatedShipments object. | | | positions | array of objects | An array of all geo-positions related to the shipment. | | | positions.dateTime | string | The time the recorded position. | This will be returned in UTC. | | positions.recievedDateTime | string | The time the position was received by project44. | This will be returned in UTC. | | positions.routeSegmentId | string | The ID of the route segment the stop is related to. | | | positions.latitude | number | The geographic latitude of the shipment position. | | | positions.longitude | number | The geographic longitude of the shipment position. | |

Error

If there was a problem with your request, you will receive one of the following error codes

  • 400 Invalid request
  • 401 Invalid or missing credentials
  • 403 User not authorized to perform this operation

See Error Response Codes in the Appendix for more information on the meaning of these error codes.

Get Route Information

Get route information (stops and route segments) for an Ocean shipment.

Requirements

  • project44-generated Shipment ID (the id returned in the 200 OK response during Shipment Creation)

Worfklow

Complete the following steps.

  1. Prepare a GET request to /api/v4/shipments/{shipmentId}/tracking using the Master Shipment ID. For example, GET /api/v4/shipments/93294f58-f87a-48e0-9f68-7d3f6e0aaa2f/tracking.

    Arguments

    NameTypeDescriptionNotes
    shipmentIdstringPath Parameter. The project44-generated id returned in the 200 OK response during Shipment Creation.This field is required.

  2. Send the request.

Expected System Response

You have successfully submitted the request when you receive a 200 OK response. Here is a sample of the response schema:

JSON
{
  "id": "string",
  "identifiers": [
    {
      "type": "WAGON_ID",
      "value": "string"
    }
  ],
  "routeInfo": {
    "stops": [
      {
        "id": "string",
        "type": "ORIGIN",
        "location": {
          "id": "string",
          "name": "string",
          "identifiers": [
            {
              "type": "RAIL_SPLC",
              "value": "string"
            }
          ],
          "address": {
            "postalCode": "string",
            "addressLines": [
              "string"
            ],
            "city": "string",
            "state": "string",
            "country": "DE"
          },
          "coordinates": {
            "latitude": 0,
            "longitude": 0
          },
          "timeZone": "string"
        }
      },
      {
        "id": "string",
        "type": "DESTINATION",
        "location": {
          "id": "string",
          "name": "string",
          "identifiers": [
            {
              "type": "RAIL_SPLC",
              "value": "string"
            }
          ],
          "address": {
            "postalCode": "string",
            "addressLines": [
              "string"
            ],
            "city": "string",
            "state": "string",
            "country": "DE"
          },
          "coordinates": {
            "latitude": 0,
            "longitude": 0
          },
          "timeZone": "string"
        }
      }
    ],
    "routeSegments": []
  "relatedShipments": [
  ]
}

This is an example of what could be returned in the response. Null fields will not show up in the response. Please refer to the API Reference documentation for more information on required and potential null fields.

See the Appendix for descriptions of Rail Shipment Stop Types and Route Segment Identifiers.

Fields and Objects

| Field | Type | Description | Notes | | --- | --- | --- | --- | --- | | id | string | The Master Shipment ID of the shipment. | This field is returned in the 200 OK response during shipment creation. | | | identifiers | string | The shipment identifier. This is different from the master shipment id (id). | The shipment ID is necessary for getting tracking information, updating a shipment, and deleting a shipments. | | identifiers.type | string | The shipment identifier type. |

Valida EU values: WAGON_ID, TRAIN_NUMBER

Valida NA values: CONTAINER_ID, TRAILER_ID, RAIL_CAR_ID, BILL_OF_LADING, WAYBILL

| | identifiers.value | string | The shipment identifier value. | | | routeInfo | object | An object of the shipment's route information. | | | routeInfo.stops | array | A stop is a set point of the journey that can be an inland location or a port. Several data fields are used to describe an array of stops as defined in the API. | | | routeInfo.stops.id | string | The project44 ID of the stop the event is related to (referenced to as stopId in events payload). | | | routeInfo.stops.type | string | The type of the stop. For descriptions of specific stop types, see the Rail Stop Types in the Appendix. | | | routeInfo.stops.location | object | An object that consists of the location name, identifiers, and coordinates. | | | routeInfo.stops.location.name | string | The name of the location – received by shipping line. | No input from the customer is required. | | routeInfo.stops.location.identifiers | string | A type:value pair – ports populate with UN LOCODE. | | | routeInfo.stops.location.coordinates | object of numbers | The latitude and longitude of the location. | | | routeInfo.routeSegments | array of objects | An array that describes the journey between two stops. | | | relatedShipments | array of objects | An array of all containers tracked under the overall shipment (as created by the user) is returned in the relatedShipments object. | |

Errors

If there was a problem with your request, you will receive one of the following error codes:

  • 400 Invalid request
  • 401 Invalid or missing credentials
  • 403 User not authorized to perform this operation

See Error Response Codes in the Appendix for more information on the meaning of these error codes.

Get Full Tracking History

Get an Ocean shipment's full tracking history including route information and stops, states, events, and positions.

Requirements

  • project44-generated Shipment ID (the id returned in the 200 OK response during Shipment Creation)

Workflow

Complete the following steps.

  1. Prepare a GET request to /api/v4/shipments/{shipmentId}/tracking/history using the Master Shipment ID. For example, GET /api/v4/shipments/93294f58-f87a-48e0-9f68-7d3f6e0aaa2f/tracking/history.

    Arguments

    NameTypeDescriptionNotes
    shipmentIdstringPath Parameter. The project44-generated id returned in the 200 OK response during Shipment Creation.This field is required.

  2. Send the request.

Expected System Response

You have successfully submitted the request when you receive a 200 OK response. Here is a sample of the response schema:

JSON
{
  "shipment": {
    "id": "string",
    "identifiers": [
      {
        "type": "TRAIN_NUMBER",
        "value": "string"
      }
    ],
    "routeInfo": {
      "stops": [
        {
          "id": "string",
          "type": "ORIGIN",
          "location": {
            "id": "string",
            "name": "string",
            "identifiers": [
              {
                "type": "string",
                "value": "string"
              }
            ],
            "address": {
              "postalCode": "string",
              "addressLines": [
                "string"
              ],
              "city": "string",
              "state": "string",
              "country": "DE"
            },
            "coordinates": {
              "latitude": 0,
              "longitude": 0
            },
            "timeZone": "string"
          }
        }
      ],
      "routeSegments": []
    },
    "relatedShipments": [],
    "shipmentShareLink": "string",
    "createdDateTime": "string",
    "lastModifiedDateTime": "string"
  },
  "states": [
    {
      "type": "SCHEDULED",
      "startDateTime": "string",
      "endDateTime": "string",
      "stopId": "string",
      "routeSegmentId": "string"
    }
  ],
  "events": [
    {
      "dateTime": "string",
      "receivedDateTime": "string",
      "type": "TRACKING_START",
      "description": "string",
      "stopId": "string",
      "routeSegmentId": "string",
      "estimateDateTime": "string",
      "estimateLastCalculatedDateTime": "string",
      "plannedDateTime": "string",
      "plannedEndDateTime": "string"
    }
  ],
  "positions": [
    {
      "dateTime": "string",
      "receivedDateTime": "string",
      "routeSegmentId": "string",
      "latitude": 0,
      "longitude": 0
    }
  ]
}

This is an example of what could be returned in the response. Null fields will not show up in the response. Please refer to the API Reference documentation for more information on required and potential null fields.

The response returned here for the Full Tracking History is the same response returned with the webhook. For more information on setting up a webhook to receive Full Tracking History updates, see Webhooks.

See the Appendix for descriptions of Rail Shipment Stop Types, Route Segment Identifiers, Rail Shipment State Types, and Rail Shipment Event Types.

Fields and Objects

| Field | Type | Description | Notes | | --- | --- | --- | --- | --- | | id | string | The Master Shipment ID of the shipment. | This field is returned in the 200 OK response during shipment creation. | | | identifiers | string | The shipment identifier. This is different from the master shipment id (id). | The shipment ID is necessary for getting tracking information, updating a shipment, and deleting a shipments. | | identifiers.type | string | The shipment identifier type. |

Valida EU values: WAGON_ID, TRAIN_NUMBER

Valida NA values: CONTAINER_ID, TRAILER_ID, RAIL_CAR_ID, BILL_OF_LADING, WAYBILL

| | identifiers.value | string | The shipment identifier value. | | | routeInfo | object | An object of the shipment's route information. | | | routeInfo.stops | array | A stop is a set point of the journey that can be an inland location or a port. Several data fields are used to describe an array of stops as defined in the API. | | | relatedShipments | array of objects | An array of all containers tracked under the overall shipment (as created by the user) is returned in the relatedShipments object. | | | states | array of objects | An array of all states the shipment was or currently is in. | | | states.type | string | The specific type of state the shipment was in. | See the Rail Shipment State Types in the Appendix for a full list of the supported state types and their descriptions. | | states.startDateTime | string | The time this state began. | This will be returned in UTC. | | states.endDateTime | string | The time that this state ended. May not be populated if the shipment is still in this state. This will be returned in UTC. | | states.stopId | string | The ID of the related stop.routeSegmentId: the route segment ID this state occurred along. | | | events | array of objects | An array of all events related to the shipment. | | | events.dateTime | string | The time at which the event took place (actual). | This will be returned in UTC. | | events.receivedDateTime | string | The last time information about event was modified. | | | events.type | string | The type of event that occurs. | See the Rail Shipment Event Types table in the Appendix for a full list of supported event types and descriptions. | | events.stopId | string | The project44 ID of the stop the event is related to. | | | events.estimateDateTime | string | project44’s latest estimated time for the event. | This will be returned in UTC. | | events.estimatedLastCalculatedDateTime | string | The last time the estimate date time was modified. | This will be returned in UTC. | | events.plannedDateTime | string | The carrier’s latest scheduled time for the event. |

Timestamps related to an event do not currently include contracted time or initial planned time by carrier.

This will be returned in UTC.

| | positions | array of objects | An array of all geo-positions related to the shipment. | | | positions.dateTime | string | The time the recorded position. | This will be returned in UTC. | | positions.recievedDateTime | string | The time the position was received by project44. | This will be returned in UTC. | | positions.routeSegmentId | string | The ID of the route segment the stop is related to. | | | positions.latitude | number | The geographic latitude of the shipment position. | | | positions.longitude | number | The geographic longitude of the shipment position. | |

Errors

If there was a problem with your request, you will receive one of the following error codes:

  • 400 Invalid request
  • 401 Invalid or missing credentials
  • 403 User not authorized to perform this operation

See Error Responses in the Appendix for more information on the meaning of these error codes.

Previous page
Next page