Portcast API version 1 to version 2 - Migration Guide

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.