The Portcast platform regroups the main carrier tracking onto a single platform, allowing you to easily get access to unified data for all major container carriers. However, there are still situations where some data might be harder to ingest or access. These include:
In order to empower Portcast users in situations like these, we’ve developed the Custom Journey feature, which is part of our Bring Your Own Data (BYOD) set of functionality. This allows our platform customers to provide their own custom data events, and have them ‘stitched together’ with the events that Portcast provides natively. This allows a much wider and full journey view of your container tracking.
<aside> 💡
In order to do this, you will need some API integration to insert and update events for specific containers; in this guide, we will link to the Portcast documentation for the API part of implementation. Once data is inserted and updated via API, you will be able to view it directly on the UI.
</aside>
In order to ingest custom events, we have created a normalized object structure that has been designed to allow a number of uses cases and transport methods. We’ve made it intentionally open so that an event can be as complex or as simple as needed depending on the use case.
At its simplest, an event should include:
event_name
describing what the event refers to;event_time
(for events that have already occurred) or event_time_estimated
(for future events that are yet to occur but that might have an estimated time of occurrence)Based on the time provided in the above fields, the Portcast ingestion system will combine the events along with the journey milestones on the platform and provided an updated milestone view including both (examples on that below).
Nevertheless, the ingestion possibilities are much wider and can be much more standardized to ensure a better integration with the container tracking milestones. Here is a full list of the supported fields that can be ingested:
field | type / required | description |
---|---|---|
custom_data | object | optional |
event_time | string<timestamp> | required (or optional if event_time_estimated provided) |
event_time_estimated | string<timestamp> | required (or optional if event_time provided) |
event_description | string | optional |
event_name | string | required |
event_type | string | optional |
Possible values: PICKUP
, GATEIN
, LOAD
, DEPART
, ARRIVE
, UNLOAD
, GATEOUT
, DELIVER
, RETURN
, T/S BERTHING
, POD BERTHING
, IN TRANSIT
, UNCLASSIFIED
If not provided, the default is UNCLASSIFIED
. |
| location | object | optional | Object containing location information for the event. Can contain partial information depending of the nature of the event. |
| → city | string | optional | City of the location where the event took place |
| → code | string | optional | Identifier code for the location (LOCODE) |
| → coordinates | object | optional | Object containing the latitude and longitude of the location of the event. |
| → country | string | optional | Country name of the event location |
| → country_code | string | optional | ISO code (alpha-2) of the country of the event location. Example: SG, IT, US |
| → name | string | optional | Name of the location of the event (port name) |
| → region | string | optional | Region of the event location |
| → type | string | optional | Type of location (PORT) |
| planned | boolean | optional | Whether this event is planned (in the future) or not. Should be combined with event_time_estimated
|
| source | string | optional | The source where the event was collected. |
| transport | object | optional | Object containing information for the transport method of the event. |
| → carrier | string | optional | The name of the carrier entity in charge of the transport. |
| → carrier_no | string | optional | The ID of the carrier entity in charge of the transport (SCAC number) |
| → id_number | string | optional | An ID number that identifies the transport method (IMO number) |
| → mode | string | optional | Mode of transportation used (VESSEL) |
| → name | string | optional | Name of the transport vehicle (vessel name) |
| → route | string | optional | In ID number/reference that identifies a recurring scheduled route used for transport (route ID) |
These fields and sub-fields should then be combined onto a JSON format payload, that can be ingested using the relevant endpoints in our API: you should use a POST call for inserting a new entry, and a PUT call for updating an existing entry.