Portcast API version 1 to version 2 - Migration Guide

Modified on Fri, 28 Jul 2023 at 03:48 AM

Portcast API version 2 Migration Guide

To access the new version, you just need to update the base URL from https://api.portcast.io/api/v1/eta to https://api.portcast.io/api/v2/eta when accessing the Portcast API.

Version 2 is targeted to be a cleaner and more granular version of Portcast API, where we've removed various deprecated keys and added more context to the arrival and departure milestones shared. To know more about the different data sources for the arrivals and departures offered, please refer to our API documentation here!

Once you change the base URL, you need to make sure that if you're using any of the following keys in your system, they are updated to the new key names from the version 2 of the API. Red denotes deprecated keys which are to be removed & blue denotes keys which are to be replaced:

  • Bill of Lading:
    • actual_delivery_time ➡ deprecated
    • actual_receipt_time ➡ deprecated
    • cbm ➡ deprecated
    • kgs ➡ deprecated
    • pod_actual_departure_lt ➡ pod_actual_departure_lt_from_ais
    • pod_actual_arrival_utc ➡ pod_actual_arrival_lt [removed the utc key, please use the local time key]
    • pod_predicted_arrival_utc ➡ pod_predicted_arrival_lt [removed the utc key, please use the local time key]
    • pod_predicted_discharge_lt deprecated
    • pod_scheduled_departure_lt ➡ pod_scheduled_departure_lt_from_schedule
    • pol_actual_arrival_lt ➡ pol_actual_arrival_lt_from_ais
    • pol_predicted_loading_lt deprecated
    • pol_scheduled_arrival_lt ➡ pol_scheduled_arrival_lt_from_schedule
    • scheduled_delivery_time deprecated
    • scheduled_receipt_time deprecated
  • Bill of Lading Bookmark:
    • customer_id deprecated
    • customer_no deprecated
    • voyage_no deprecated
  • Container Meta Info deprecated
  • Sailing Info Tracking:
    • actual_arrival_lt ➡ sailing_info.pod_actual_arrival_lt
    • actual_arrival_utc  sailing_info.pod_actual_arrival_lt [removed the utc key, please use the local time key]
    • cancelled  deprecated
    • predicted_arrival_lt  sailing_info.pod_predicted_arrival_lt
    • predicted_arrival_utc  sailing_info.pod_predicted_arrival_lt [removed the utc key, please use the local time key]
    • prediction_confidence_level  deprecated
    • prediction_time_utc  deprecated
    • scheduled_arrival_lt  sailing_info.pod_scheduled_arrival_lt
    • scheduled_arrival_utc  sailing_info.pod_scheduled_arrival_lt [removed the utc key, please use the local time key]
    • target_port_code ➡ sailing_info.pod
    • target_port_eta ➡ sailing_info.pod_predicted_arrival_lt
    • target_port_name  sailing_info.pod_name
    • voyage_no_list  deprecated
    • AIS:
    • draught_m  deprecated
    • Sailing Info:
    • pod_actual_departure_lt  pod_actual_departure_lt_from_ais
    • pod_predicted_discharge_lt  deprecated
    • pod_scheduled_departure_lt  pod_scheduled_departure_lt_from_schedule
    • pol_actual_departure [Duplicate key]  pol_actual_departure_lt
    • pol_actual_arrival_lt  pol_actual_arrival_lt_from_ais
    • pol_predicted_loading_lt  deprecated
    • pol_scheduled_arrival_lt  pol_scheduled_arrival_lt_from_schedule
    • status  deprecated
    • status_code  deprecated
    • Voyage Details
    • original_voyage_no  deprecated
    • scheduled_arrival_on_time_confidence  deprecated
    • scheduled_departure_on_time_confidence  deprecated

In addition to the above, it's also important to take into consideration the following behavioural changes:     

  • For Bill of Lading & Sailing Info:
    • pol_scheduled_departure_lt & pol_actual_departure_lt will only container data from carrier's track & trace details, hence it would be blank when the carriers doesn't provide it. In which case, pol_scheduled_departure_lt_from_schedule pol_actual_departure_lt_from_ais will be more reliable.    
    • Similarly for POD, pod_scheduled_arrival_lt & pod_actual_arrival_lt will only contain data from carrier's track and trace details, hence would be blank when the carrier doesn't provide it. In which case, pod_scheduled_arrival_lt_from_schedule & pod_actual_arrival_lt_from_ais would be more reliable.
  • For container events list, we've also added 2 new keys called as vessel_name & vessel_imo which would contain the corresponding vessel details for the container event as seen on the carrier's track and trace.

If you have any questions regarding the removal of any of the above fields or regarding the migration, feel free to reach out to your portcast account manager or our team at support@portcast.io and we'd be happy to provide guidance.

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select atleast one of the reasons

Feedback sent

We appreciate your effort and will try to fix the article