API Developer's Guide

 

This guide is intended for developers who want to integrate their own applications with PortConnect.

What is the PortConnect API?


The PortConnect API (Application programming interface) is a new, more modern way of sending and retrieving data from PortConnect.  PortConnect receives container event information 24 hours a day from our partner ports Ports of Auckland, Port of Tauranga and the Timaru Container Terminal.  Events are received at least every ten minutes.

All API operations work for all partner ports.

  • Scheduled vessels: Returns scheduled vessel information, including expected time of arrival and departure.

  • Containers: Returns the latest detailed information for specified containers.  Up to 10 containers can be searched at any one time.

  • Container event subscriptions: This is a suite of operations which allows container events to be sent to any end point you specify.

Getting Started


Signing Up

In order to use the PortConnect API, you need to sign up to our Microsoft APIM based developer portal, which is located at https://developer.portconnect.io.  Signing up is free of charge.  

Once signed up, you will be able to subscribe to either the Full Access or Trial product variations for the API, via the "Products" menu.  Both products contain the same API end points, and both products require you to accept the PortConnect API terms and conditions of use.

The Trial version restricts the number of requests that you can make to an API end point to 100 calls within a 24 hour period.  Full Access has no restrictions on the number of requests you can make, however some charges may apply.

Once the subscription is confirmed, an API key will be generated.  You can see your API key from the profile menu. 

All calls to the PortConnect API must include either the primary or secondary key in the header Ocp-Apim-Subscription-Key.  You can regenerate your subscription key any time you choose.

Developer Portal

The Developer Portal is a useful tool that provides documentation for end points and auto-generated definitions for API object models. It also includes a test function that allows you to test API calls against our live data.

The PortConnect API endpoint to use from your client application is https://api.portconnect.io.  The developer portal can generate sample code in a number of different programming languages:

 

 

 

Feel free to use other API tools such as Postman.  See the resources section below for some Postman tests you can use.

API Endpoints


Scheduled Vessels

This end point returns vessels that are scheduled to arrive at our partner ports. It can also be used to query vessels currently in port and vessels that have recently departed. This data is updated approximately every 15 minutes.

Refer to the scheduled vessels documentation in the  developer portal for details on parameters you can use:

Examples

This request will return all commercial vessels (excludes cruise ships) for Auckland that are expected to arrive between 2nd May 12:00am and 31st May 12:00 am:

1 https://api.portconnect.io/v1/scheduled-vessels?portCode=NZAKL&vesselType=COMMERCIAL&vesselStatus=EXPECTED&arrivalDateFrom=2022-05-02&arrivalDateTo=2022-05-31

This request will return all commercial vessels (excludes cruise ships) for Auckland that are expected to arrive between 1:00pm and 2:00pm on the 2nd May.  Times are NZ Daylight saving:

1 https://api.portconnect.io/v1/scheduled-vessels?portCode=NZAKL&vesselType=COMMERCIAL&vesselStatus=EXPECTED&arrivalDateFrom=2022-05-02T13:00:00&arrivalDateTo=2022-05-02T14:00:00

Response

The response data is the same as that returned via the vessel schedule screen on the PortConnect website, and should be self-explanatory:

Scheduled Vessel Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 [{ "vesselVisitReference": "TEM6916", "vesselName": "THEMIS", "imoNumber": "9722314", "inboundVoyage": "FF920", "outboundVoyage": "FF920", "vesselStatus": "EXPECTED", "vesselType": "COMMERCIAL", "portCode": "NZAKL", "wharfName": "BLEDISLOE", "previousPortName": "MANZANILLO", "nextPortName": "BRISBANE", "vesselOperator": "WILHELMSEN LINES NZ LTD", "serviceCode": "WILHELMSEN SERVICE", "arrivalDatetime": "2019-05-02T13:30:00+12:00", "departureDatetime": "2019-05-02T23:34:00+12:00", "receivalCommenceInland": null, "receivalCommenceSeaport": null, "receivalCutoffInland": null, "receivalCutoffSeaport": null, "lastUpdatedDateTime": "2019-05-02T13:05:21.913+12:00" }]

Container Visits

In PortConnect terminology, a container visit refers to a container passing through a partner port.  The container visit might be an import, export, transhipment or a domestic supply chain movement.

Using the container visits search API, you can search for a single container or up to 10 containers in a single call. 

Examples

The following api request will return information on the containers TCLU5458530 and TCLU5614930 for Auckland:

1 https://api.portconnect.io/v1/container-visits?containerNumber=TCLU5458530&portCode=NZAKL&containerNumber=TCLU5614930

Response

The response contains the currently active or the most recent container visit record, and the field names should be self explanatory:

Example response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 [{ "containerVisitId": 7616216, "portCode": "NZTRG", "category": "EXPORT", "containerNumber": "MSKU1512500", "shipmentDirection": "OUTBOUND", "inboundVesselRef": null, "inboundVesselName": null, "inboundVesselPublishedArrivalDatetime": null, "inboundVesselActualArrivalDatetime": null, "inboundVesselPublishedDepartureDatetime": null, "inboundVesselActualDepartureDatetime": null, "outboundVesselRef": "RIB917N", "outboundVesselName": "RIO BLANCO", "outboundVesselPublishedArrivalDatetime": "2019-05-05T15:30:00+12:00", "outboundVesselActualArrivalDatetime": null, "outboundVesselPublishedDepartureDatetime": "2019-05-06T21:30:00+12:00", "outboundVesselActualDepartureDatetime": null, "containerIsoTypeCode": "4510", "containerIsoTypeDescription": "40' 9'6 HIGH CUBE", "declaredWeight": 30430.0, "declaredWeightVgm": true, "commodityCode": "FAK", "containerStatus": "FULL", "requiredTemperature": 0.0, "ventSetting": null, "o2Percent": null, "cO2Percent": null, "humidityPercent": null, "packedOffPowerDatetime": null, "PackedOffPowerTemp": null, "maxHoursAllowedOffPower": null, "containerOperatorCode": "MAEU", "containerOperatorName": "Maersk Line", "containerOperatorVoyageId": "917N", "loadPortCode": "NZTRG", "loadPortName": "Tauranga", "dischargePortCode": "MYTPP", "dischargePortName": "Tanjung Pelepas", "destinationPortCode": "INVTZ", "destinationPortName": "Visakhapatnam", "inlandPortArrivalDatetime": null, "inlandPortCarrier": null, "seaPortCarrier": "B340 (Road)", "loadDatetime": null, "receivedDatetime": "2019-05-02T13:44:31.017+12:00", "inlandPortInboundCarrier": null, "seaPortArrivalDatetime": "2019-05-02T13:44:31.017+12:00", "seaPortInboundCarrier": "B340 (Road)", "bookingReference": "968486382", "cedoNumberCode": null, "dischargedDatetime": null, "deliveredDatetime": null, "securityCheck": null, "lastFreeDatetime": null, "lineReleaseDatetime": null, "customsReleaseDatetime": null, "mpiReleaseDatetime": null, "containerLocation": "YARD", "emptyReturnDepotCode": null, "emptyReturnDepotName": null, "sealCount": 1, "hazardCount": 0, "stopCount": 1, "oversizeCount": 0, "seals": [{ "containerSealTypeCode": "Other", "containerSealValue": "FJO3729049" }], "hazards": [], "stops": [{ "stopTypeCode": "!NO VGM NO VESSEL LOAD" }], "oversizes": [] }]

Returning a single container visit

If you have a single container visit id, which is a PortConnect reference to a unique container visit, you can also retrieve container data by putting the id in the path of the container visits uri.  For instance this request returns the same information as the above example:

1 https://api.portconnect.io/v1/container-visits/7616216

Container Event Subscriptions

Use container event subscriptions, or "subscriptions", when you want PortConnect to send you an http (“webhook”) callback when a particular container event occurs.  This is an alternative to the email / xml based notifications which are also operated by PortConnect.

There are now two versions of the container event subscription API. These are differentiated by a version number in the URI: https://api.portconnect.io/v1/subscriptions and https://api.portconnect.io/v2/subscriptions respectively. Key differences between version 1 (V1) and version 2 (V2) are described in each section below.

Creating a Subscription

To receive callbacks for particular container events, you need to create a subscription by posting a request the subscriptions endpoint. Version 1 requests a single container visit event type code per request, Version 2 supports multiple container visit event type codes in a single request. Version 2 also supports the use of “ALL” to subscribe to all events for one or more containers.

Version 1

Each subscription relates to a single event type, however multiple containers can be included. 

For version 1, a new subscription is created for every unique combination of PortCodeCategoryEventTypeCode and FacilityCode .  If a subscription already exists for a particular combination, then containers are added to that subscription.

Subscription V1 Create Example

For example, the following subscription request will result in a webhook callback when any of the three specified import containers become available:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 POST https://api.portconnect.io/v1/subscriptions HTTP/1.1 { "containers": [ { "containerNumber": "MEDU3085895", "userDefinedReference" : "User ref 1"}, { "containerNumber": "APHU6303593", "userDefinedReference" : "User ref 2"}, { "containerNumber": "MEDU5129708", "userDefinedReference" : "User ref 3"} ], "webhookURI": "https://api.yourcompany.co.nz/webhooks/portconnect", "webhookToken": "yoursecret", "portCode": "NZTRG", "category": "IMPORT", "eventTypeCode": "AVAILABLE", "facilityCode": null }

Version 2

Version 2 of the subscription API supports multiple container event types, as well as the of “ALL” to subscribe to all possible events. Event type codes are supplied as an array.

For version 2, a new subscription is created for every unique combination of PortCodeCategory and FacilityCode .  If a subscription already exists for a particular combination, then containers are added to that subscription.

Subscription V2 Create Example
1 2 3 4 5 6 7 8 9 10 11 12 POST https://api.portcon2nect.io/v2/subscriptions HTTP/1.1 { "portCode": "NZTRG", "category": "IMPORT", "eventTypeCodes": ["DISCHARGE", "AVAILABLE"], "webhookURI": "https://enb8apr7yans.x.pipedream.net", "webhookToken": "123-456-789-000", "facilityCode": null, "containers": [{"containerNumber": "TCNU8050683", "userDefinedReference" : "Azure Test 2"} ] }

Request Validation Rules

You must specify the uri location where you want the webhook callback to be sent, and optionally a token that you can use to verify the call. Other rules common to both versions are:

  • Valid port codes are: NZAKLNZTRG, NZTIU or NZLYT

  • Valid category codes are: IMPORTEXPORTTRANSHIPMENTDOMESTIC

  • Facility codes are optional and relate to the port facility where the event takes place. If no facility code is specified, then webhook callbacks will be sent whenever the event occurs, regardless of the location.  For instance, if a subscription is created for an export "gate in", and the container is gated in to both an inland port and the sea port, then two gate in events will be sent as webhook callbacks.

  • Only some event type codes support the use of the facility code, in all other cases a null value should be supplied.  Refer to the table below.

User Defined References

  • We only permit one userDefinedReference per container. This is a maximum of 50 characters and designed to support container visit identifiers in calling systems.

  • The user defined reference will be included in the webhook callback payload against the specified container.

  • If you create a new subscription with a different user defined reference, it will overwrite the existing subscription including the user defined reference.

  • If you have already received events against the first subscription you will receive future events against the new subscription with the new user defined reference.


Notification Types

Valid event type codes are shown in the following table, along with event values that are returned in the webhook callback payload:

Code

Description

Supported Facility Codes

Event Value 1

Event Value 2

Code

Description

Supported Facility Codes

Event Value 1

Event Value 2

ACTIVE

Container record becomes live in PortConnect system

NZAKL, NZTRG, NZTIU, NZLYT





AVAILABLE

Availability Advice (Container is fully released)

NZAKL, NZTRG, NZTIU, NZLYT





AVAILABLECANCELLED

Availability Advice cancelled

NZAKL, NZTRG, NZTIU, NZLYT





BOOKINGDISCREPANCY

Discrepancy: Booking does not match Preadvise/Gate-in details

NZAKL, NZTRG, NZTIU, NZLYT

Container Visit value

Booking value

CLEARED

Cleared Advice (Container is fully cleared)

NZAKL, NZTRG, NZTIU, NZLYT





CLEAREDCANCELLED

Cleared Advice cancelled

NZAKL, NZTRG, NZTIU, NZLYT





CUSTOMSRELEASE

Notice of Customs Release

NZAKL, NZMKL, NZTRG, NZTIU, NZLYT, NZOLT





CUSTOMSRELEASECANCELLED

Notice of Customs Release cancelled

NZAKL, NZMKL, NZTRG, NZTIU, NZLYT, NZOLT





DEPART

Facility Departure Advice

NZAKL, NZWII





DISCHARGE

Discharge Advice

NZAKL, NZTRG, NZTIU, NZLYT





EXPORTCLEARED

CEDO is in place and there are no other stops

NZAKL, NZTRG, NZTIU, NZLYT





EXPORTCLEAREDCANCELLED

Export Cleared cancelled

NZAKL, NZTRG, NZTIU, NZLYT





GATEIN

Gate IN advice

NZAKL, NZMKL, NZTRG, NZWII, NZTIU, NZOLT

Mode of transport, eg. Road

Identifier for the truck or train, eg. REL328

GATEOUT

Gate OUT Advice

NZAKL, NZMKL, NZTRG, NZWII, NZTIU, NZOLT, NZLYT, NZCHC

Mode of transport, eg. Road

Identifier for the truck or train, eg. REL328

HAZARDGATERULE

Hazardous Cargo Gate-in rule applies

NZAKL, NZTRG, NZTIU, NZLYT





LFT24HOURS

Container visit Last Free Time within 24 hours

NZAKL, NZTRG, NZTIU

Last free time



LFTCHANGED

Container visit Last Free Time has been changed

NZAKL, NZTRG, NZTIU

New last free time



LFTEXCEEDED

Container visit Last Free Time exceeded

NZAKL, NZTRG, NZTIU

Last free time



LOAD

Notice of item loaded to Vessel

NZAKL, NZTRG, NZTIU, NZLYT





LOPRELEASE

Notice of Line Operator Release

NZAKL, NZMKL, NZTRG, NZTIU, NZOLT, NZLYT, NZCHC





LOPRELEASECANCELLED

Notice of Line Operator Release - cancelled

NZAKL, NZMKL, NZTRG, NZTIU, NZOLT, NZLYT, NZCHC





MPIRELEASE

Notice of MPI Release

NZAKL, NZMKL, NZTRG, NZTIU, NZOLT, NZLYT, NZCHC





MPIRELEASECANCELLED

Notice of MPI Release - cancelled

NZAKL, NZTRG, NZTIU, NZLYT





NOCEDO

No Cedo Warning

NZAKL, NZTRG, NZTIU, NZLYT

48, 24, 2 hour warning text



PINAVAILABLE

ExpressPin Available

NZAKL

Express Pin number



PINSUSPENDED

ExpressPin Suspended

NZAKL

Express Pin number



VESSELARRIVAL

Vessel Visit Actual Time of Arrival

NZAKL, NZTRG, NZTIU, NZLYT





VESSELDEPARTURE

Vessel Visit Actual Time of Departure

NZAKL, NZTRG, NZTIU, NZLYT





PRIORITYGATEIN

Automated Gate-In Notifications when containers arrive at Metroport with a status of Priority (Only available for Imports via Port of Tauranga).

NZTRG






Facility codes:

  • NZAKL - Ports of Auckland 

  • NZMKL - MetroPort Auckland

  • NZCWF - Crawford Street, Hamilton

  • NZTRG - Port of Tauranga, Sulphur Point

  • NZWII - Wiri, Ports of Auckland South Auckland Freight Hub

  • NZTIU - Timaru Container Terminal

  • NZOLT - MetroPort Rolleston

  • NZLYT - Lyttelton Port Company

  • NZCHC - CityDepot

 

Response

Success will result in a return code of 201 Created. The response to the request will confirm the containers in the subscription. 

Subscription Create Response (V1 and V2)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 { "subscriptionId": 9, "containers": [ { "expirationDatetime": "2019-08-19T10:51:29.163+12:00", "subscriptionContainerId": 12, "containerNumber": "APHU6303593", "userDefinedReference" : "User ref 1" }, { "expirationDatetime": "2019-08-19T10:51:29.163+12:00", "subscriptionContainerId": 11, "containerNumber": "MEDU3085895", "userDefinedReference" : "User ref 2" }, { "expirationDatetime": "2019-08-19T10:51:29.163+12:00", "subscriptionContainerId": 13, "containerNumber": "MEDU5129708", "userDefinedReference" : "User ref 3" } ] }

The response includes a subscription id.  You can use the subscription id as a handle for future get, update and delete calls.

Each container includes a subscriptionContainerId, which you can use as a reference as this is passed back in the webhook payload. 

The expiration datetime for the container is also shown.  Each container in a subscription has an expiration date of the creation date plus 60 calendar days.  After this time no callbacks will be made for the container, and the container is no longer returned when querying the subscription. Calling the subscription create event with the same container number will extend the expiration datetime.

Webhook Callback Payload

When PortConnect detects an event that matches your subscription, it will send an HTTP POST to your specified end point.  Event matching happens when new events are processed into the PortConnect system,and also when the subscription is first created (for events that have occurred for a currently active container).

For testing purposes, you may find it useful to create a webhook uri using Request Bin or similar.  This allows you to easily view the webhook payload.

Example

Multiple events may be returned in a single payload, as in this example:

Webhook Callback Payload
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 [ { "subscriptionEventId": 13752, "subscriptionId": 9, "partnerPortCode": "NZAKL", "containerVisitTypeCode": "EXPORT", "containerVisitEventTypeCode": "GATEIN", "containerVisitEventDatetime": "2019-06-19T12:41:02+12:00", "containerVisitEventLocation": "NZAKL", "containerNumber": "APHU6303593", "containerIsoTypeCode": "4510", "containerVisitUri": "v1/container-visit/5046168", "subscriptionContainerId": 12, "userDefinedReference": "User ref 1", "containerVisitEventValue": "Road", "containerVisitEventValue2": "REL328", "inboundVesselRef":null, "inboundVesselName":null, "inboundVesselIMONumber":null, "outboundVesselRef":"KOC0130", "outboundVesselName":"KOTA LOCENG", "outboundVesselIMONumber":9628336 }, { "subscriptionEventId": 13752, "subscriptionId": 9, "partnerPortCode": "NZAKL", "containerVisitTypeCode": "EXPORT", "containerVisitEventTypeCode": "GATEIN", "containerVisitEventDatetime": "2019-06-19T12:41:02+12:00", "containerVisitEventLocation": "NZAKL", "containerNumber": "MEDU3085895", "containerIsoTypeCode": "2210", "containerVisitUri": "v1/container-visit/5046572", "subscriptionContainerId": 11, "userDefinedReference": "User ref 2", "containerVisitEventValue": "Road", "containerVisitEventValue2": "REL328", "inboundVesselRef":null, "inboundVesselName":null, "inboundVesselIMONumber":null, "outboundVesselRef":"KOC0130", "outboundVesselName":"KOTA LOCENG", "outboundVesselIMONumber":9628336 }, { "subscriptionEventId": 13752, "subscriptionId": 9, "partnerPortCode": "NZAKL", "containerVisitTypeCode": "EXPORT", "containerVisitEventTypeCode": "GATEIN", "containerVisitEventDatetime": "2019-06-19T12:41:02+12:00", "containerVisitEventLocation": "NZAKL", "containerNumber": "MEDU5129708", "containerIsoTypeCode": "2210", "containerVisitUri": "v1/container-visit/5046997", "subscriptionContainerId": 13, "userDefinedReference": "User ref 3", "containerVisitEventValue": "Road", "containerVisitEventValue2": "REL328", "inboundVesselRef":null, "inboundVesselName":null, "inboundVesselIMONumber":null, "outboundVesselRef":"KOC0130", "outboundVesselName":"KOTA LOCENG", "outboundVesselIMONumber":9628336 } ]

Included as a header key of the callback is a value X-WebhookToken which you can choose to validate as the webhookToken value specified when creating the subscription.   This is designed to help protect your webhook end point from unauthorised access.

If you require additional information about the container visit, call the containerVisitUri returned.  Refer to the Container Visits section for details.

Searching All Subscriptions

You can search for all active container event subscriptions for your API user by invoking a GET action on the subscriptions end point with no parameters:

Subscription V1 GET All Example

1 https://api.portconnect.io/v1/subscriptions

Subscription V1 GET All Response

The response payload lists all of you current subscriptions, for example:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 [{ "subscriptionId": 9, "containers": [ { "expirationDatetime": "2019-08-19T10:51:29.163+12:00", "subscriptionContainerId": 12, "containerNumber": "APHU6303593", "userDefinedReference" : "User ref 1" }, { "expirationDatetime": "2019-08-19T10:51:29.163+12:00", "subscriptionContainerId": 11, "containerNumber": "MEDU3085895", "userDefinedReference" : "User ref 2" }, { "expirationDatetime": "2019-08-19T10:51:29.163+12:00", "subscriptionContainerId": 13, "containerNumber": "MEDU5129708", "userDefinedReference" : "User ref 3" } ], "webhookURI": "https://enhct6aieo9t7.x.pipedream.net", "webhookToken": "123-456-789-000", "portCode": "NZAKL", "category": "IMPORT", "eventTypeCode": "CUSTOMSRELEASE", "facilityCode": "" }, { "subscriptionId": 10, "containers": [ { "expirationDatetime": "2019-08-19T10:51:29.163+12:00", "subscriptionContainerId": 12, "containerNumber": "APHU6303593", "userDefinedReference" : "User ref 1" }, { "expirationDatetime": "2019-08-19T10:51:29.163+12:00", "subscriptionContainerId": 11, "containerNumber": "MEDU3085895", "userDefinedReference" : "User ref 2" }, { "expirationDatetime": "2019-08-19T10:51:29.163+12:00", "subscriptionContainerId": 13, "containerNumber": "MEDU5129708", "userDefinedReference" : "User ref 3" } ], "webhookURI": "https://enhct6aieo9t7.x.pipedream.net", "webhookToken": "123-456-789-000", "portCode": "NZAKL", "category": "IMPORT", "eventTypeCode": "AVAILABLE", "facilityCode": "" }]

Subscription V2 GET All Example

1 https://api.portconnect.io/v2/subscriptions

Subscription V2 GET All Response

The subscription V2 response returns an array of subscribed event type codes in the response.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 [ { "subscriptionId": 1395, "containers": [ { "expirationDatetime": "2022-06-11T17:15:58.997+12:00", "subscriptionContainerId": 2590903, "containerNumber": "CAIU3549296", "userDefinedReference": "LFT ISO code test 2" }, { "expirationDatetime": "2022-06-11T17:15:58.997+12:00", "subscriptionContainerId": 2590902, "containerNumber": "OOLU1858222", "userDefinedReference": "LFT ISO code test 1" }, { "expirationDatetime": "2022-06-12T15:45:34.99+12:00", "subscriptionContainerId": 2594031, "containerNumber": "TCNU8050683", "userDefinedReference": "Azure Test 2" } ], "eventTypeCodes": [ "AVAILABLE", "CUSTOMSRELEASE", "ACTIVE", "PRIORITYGATEIN" ], "category": "IMPORT", "facilityCode": "", "webhookURI": "https://enb8apr7yans.x.pipedream.net", "webhookToken": "123-456-789-000", "portCode": "NZTRG" }, { "subscriptionId": 1397, "containers": [ { "expirationDatetime": "2022-06-12T15:46:13.21+12:00", "subscriptionContainerId": 2594055, "containerNumber": "TCNU8050683", "userDefinedReference": "Azure Test 2" } ], "eventTypeCodes": [ "BOOKINGDISCREPANCY", "GATEIN", "GATEOUT", "HAZARDGATERULE", "LOAD", "NOCEDO", "PINAVAILABLE", "PINSUSPENDED", "ACTIVE", "EXPORTCLEARED" ], "category": "EXPORT", "facilityCode": "", "webhookURI": "https://enb8apr7yans.x.pipedream.net", "webhookToken": "123-456-789-000", "portCode": "NZTRG" } ]

Searching for a Single Subscription

If you know the subscription id, you can search for the details of a single subscription:

Subscription V1 Single GET Example

The following example returns the subscription details for subscription 9:

1 https://api.portconnect.io/v1/subscriptions/9

Subscription V1 Single GET Response

The response payload lists the matching subscription, for example:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 { "subscriptionId": 9, "containers": [ { "expirationDatetime": "2019-08-19T11:07:19.883+12:00", "subscriptionContainerId": 12, "containerNumber": "APHU6303593", "userDefinedReference" : "User ref 1" }, { "expirationDatetime": "2019-08-19T11:07:19.883+12:00", "subscriptionContainerId": 11, "containerNumber": "MEDU3085895", "userDefinedReference" : "User ref 2" }, { "expirationDatetime": "2019-08-19T11:07:19.883+12:00", "subscriptionContainerId": 13, "containerNumber": "MEDU5129708", "userDefinedReference" : "User ref 3" } ], "webhookURI": "https://enhct6aieo9t7.x.pipedream.net", "webhookToken": "123-456-789-000", "portCode": "NZAKL", "category": "IMPORT", "eventTypeCode": "CUSTOMSRELEASE", "facilityCode": "" }

Subscription V2 Single GET Example

The following example returns the subscription details for subscription 1397:

1 https://api.portconnect.io/v2/subscriptions/1397

Subscription V2 Single GET Response

The response payload lists the matching subscription, for example:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 { "subscriptionId": 1397, "containers": [ { "expirationDatetime": "2022-06-12T15:46:13.21+12:00", "subscriptionContainerId": 2594055, "containerNumber": "TCNU8050683", "userDefinedReference": "Azure Test 2" } ], "eventTypeCodes": [ "BOOKINGDISCREPANCY", "GATEIN", "GATEOUT", "HAZARDGATERULE", "LOAD", "NOCEDO", "PINAVAILABLE", "PINSUSPENDED", "ACTIVE", "EXPORTCLEARED" ], "category": "EXPORT", "facilityCode": "", "webhookURI": "https://enb8apr7yans.x.pipedream.net", "webhookToken": "123-456-789-000", "portCode": "NZTRG" }

Updating Subscriptions

A single subscription can be updated by sending a patch to the subscriptions end point, specifying the subscription id in the uri.  Any containers supplied replace all existing containers in the subscription.

You can update the port code, category, event type and facility codes if you wish, but this isn't recommended as a different subscription id can result, possibly causing confusion.

Example

For instance, subscription id 35 can be updated to include containers:

Subscription V1 Update
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 PATCH https://api.portconnect.io/v1/subscriptions/35 HTTP/1.1 { "containers": [ { "containerNumber": "CNIU2234429"}, { "containerNumber": "CNIU2234430"}, { "containerNumber": "CNIU2234431"}, ], "webhookURI": "https://api.yourdomain.com/portconnect", "webhookToken": "secretsquirrel", "portCode": "NZAKL", "category": "IMPORT", "eventTypeCode": "AVAILABLE", "facilityCode": "" }
Subscription V2 Update
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 PATCH https://api.portconnect.io/v1/subscriptions/45 HTTP/1.1 { "containers": [ { "expirationDatetime": "2022-06-12T15:46:13.21+12:00", "subscriptionContainerId": 2594055, "containerNumber": "TCNU8050684", "userDefinedReference": "Azure Test 2" } ], "eventTypeCodes": [ "BOOKINGDISCREPANCY", "GATEIN", "GATEOUT", "HAZARDGATERULE", "LOAD", "NOCEDO", "PINAVAILABLE", "PINSUSPENDED", "ACTIVE" ], "category": "EXPORT", "facilityCode": "", "webhookURI": "https://enb8apr7yans.x.pipedream.net", "webhookToken": "123-456-789-000", "portCode": "NZTRG" }

Response

A return code of 204 indicates the subscription has been updated successfully.

Deleting Subscriptions

Subscriptions may be deleted by sending a delete request with an empty request body to the subscriptions end point, specifying the subscription to delete as a parameter in the URI.

Delete works the same for both versions of the subscription end point.

Example

Subscription Delete
1 2 3 DELETE https://api.portconnect.io/v1/subscriptions/34 HTTP/1.1 DELETE https://api.portconnect.io/v2/subscriptions/497 HTTP/1.1

Response

A return code of 204 indicates the subscription has been deleted successfully.


Export Pre-Advice

Use the Export Pre-Advice end point to submit, retrieve and delete export pre-advice programmatically on behalf of a PortConnect user. Contact our User Support to be granted access to this end point.  PortConnect will associate an API user id with a specific PortConnect user so that export pre-advice can be submitted on behalf of that user.

Only the Ports of Auckland and the Port of Tauranga support Export Pre-advice submitted via PortConnect.

Submitting an Export Pre-advice

In order to understand the Export Pre-advice submission, some familiarity with the Export Pre-advice User Guide is recommended. This details how export pre-advice submitted via the PortConnect website. The structure of the API is conceptually very similar to this screen, comprising a header with a list of containers being submitted.

Example

This is a basic example of an export pre-advice message comprising the header with a single container record.  Additional properties allow the submission of refrigeration, vent, hazardous and over gauge settings, and these are detailed in the developer test portal.

Export pre-advice submit
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 POST https://apitest.portconnect.io/v1/export-preadvices HTTP/1.1 Host: apitest.portconnect.io Content-Type: application/json Ocp-Apim-Subscription-Key: •••••••••••••••••••••••••••••••• { "header": { "shipperName": "ALNEMAH HALAL MEAT LIMITED", "bookingReference": "1AKL026740", "pointOfOriginCode": "Bay of Plenty", "loadPortFacility": "TCT", "vessel": { "lineOperatorCode": "HSUD", "shipName": "DEBUSSY", "voyageNumber": "138N", "partnerPortShippingReference": "USY138N", "loadPortCode": "NZTRG", "portOfDischarge": "USLGB", "foreignPortOfDischarge": "USLGB" }, "notificationEmails": [ "Cameron.Pitches@portconnect.co.nz" ], "userReference": "CAMTEST001" }, "containers": [ { "containerNumber": "CDPU3736837", "isoTypeCode": "2232", "flexiTank": false, "isFull": true, "commodityCode": "0201", "isNonOperatingReefer": false, "refrigeration": { "isFantainer": false, "requiredTemperature": -5.0, "refrigerationType": "Chilled" }, "cargoWeightKg": 28000.0, "totalWeightKg": 30000.0, "containerSeals": [ { "sealType": "Shipper", "sealCode": "555" } ], "arrivalCarrierType": "Truck" } ] }

Response

A return code of 201 Created results when the export pre-advice request is submitted. Importantly, the response payload needs to be examined to determine if both the overall export pre-advice was created successfully, along with the associated container records.  For instance the above request will return success flags at the header and the container level:

Export pre-advice success
1 2 3 4 5 6 7 8 9 10 11 { "success": true, "errors": [], "containers": [ { "containerNumber": "CDPU3736837", "errors": [], "success": true } ] }

However, should the requiredTemperature value be set to -50 in the example above, then the following is returned:

Export pre-advice partial failure
1 2 3 4 5 6 7 8 9 10 11 12 13 { "success": true, "errors": [], "containers": [ { "containerNumber": "CDPU3736837", "errors": [ "Temperature too high/low for the selected commodity (Range: -5.0 to 2.0). Change commodity or contact Terminal" ], "success": false } ] }


Validation

Validation of the export pre-advice request is extensive. Validation messages are generated at the PortConnect API level and also from the partner port, such as the example above. Validation message include:

  • Must provide a valid booking

  • Load Port must match the booking

  • Load Port must be valid

  • Line Operator code must be valid

  • Line Operator code must match the booking

  • Vessel Visit must match the booking

  • Discharge Port must match the booking

  • Reefer ISO type containers must have a Temperature (unless specified as a Non-Operating Reefer)

  • Freight Kind (Full vs Empty) must match the booking

  • Reefer temperatures must match the booking

  • Conditioning details must match the booking. Conditioning details include: Humidity %, Vent value, Vent Type, O2% and CO2%

  • Hazard UN Codes must match the booking

  • Total Pre-Advised Containers must not exceed the booking quanta (count)

  • Seal Type must be valid

Email Notifications

Common to the export pre-advice screen and B2B export pre-advice functions, the export pre-advice api supports the use of email notifications. By specifying one or more email addresses in the notificationEmails property, an email is generated which confirms which containers are successfully pre-advised. This is an optional property.

The emails contain two boxes, a green box in which successful containers will display and a red box in which unsuccessful containers will display. Containers in the green box show all the key details of the container. You can use this email to share the details with other parties. Any unsuccessful containers will show in the red box with a comment about why the Pre-Advice was not successful. The same message also appears on the PortConnect website.

Other Notes

Subsequent calls using the same header information will update the container list, overwriting the previous container list with the new values.

Calls made via the API are reflected in the PortConnect Export Pre-advice screen.  For instance, if containers are added or removed, then this will be reflected on the Export Pre-Advice screen.  PortConnect also has the capability to generate an API call from the Export Pre-advice screen, which is useful for more complex scenarios.  Contact user support to find out more about this.

Codes to use for various properties are listed on this page.

Retrieving an Export Pre-Advice

An export pre-advice can be retrieved using a GET to the export-preadvices end point, specifying the port and user reference in the URL,  and optionally a container number.  Specifying the container number restricts the response to only the export pre-advice header and the container number.

Example

The following example returns all information relating to the export pre-advice submitted above.

Export pre-advice retrieve
1 2 3 4 GET https://apitest.portconnect.io/v1/export-preadvices/NZTRG/CAMTEST001 HTTP/1.1 Host: apitest.portconnect.io Content-Type: application/json Ocp-Apim-Subscription-Key: ••••••••••••••••••••••••••••••••


Validation

If an incorrect partner port code is used then a 400 Bad Request response is returned.

If the user reference is not found then a 404 Not Found response is returned.

Response

The response is the same format as the post request, with the addition of the status of the latest submission.  For example:

Export pre-advice response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 { "header": { "shipperName": "ALNEMAH HALAL MEAT LIMITED", "bookingReference": "1AKL026740", "pointOfOriginCode": "Bay of Plenty", "loadPortFacility": "TCT", "vessel": { "lineOperatorCode": "HSUD", "shipName": "DEBUSSY", "voyageNumber": "138N", "partnerPortShippingReference": "USY138N", "loadPortCode": "NZTRG", "portOfDischarge": "USLGB", "foreignPortOfDischarge": "USLGB" }, "notificationEmails": [ "Cameron.Pitches@portconnect.co.nz" ], "userName": "test-preadvice-portconnect-co-nz", "userReference": "CAMTEST001" }, "containers": [ { "latestSubmissionStatus": { "action": "Create", "success": true }, "containerNumber": "CDPU3736837", "isoTypeCode": "2232", "flexiTank": false, "commodityCode": "0201", "isNonOperatingReefer": false, "refrigeration": { "isFantainer": false, "requiredTemperature": -5.0 }, "cargoWeightKg": 28000.0, "totalWeightKg": 30000.0, "containerSeals": [ { "sealType": "Shipper", "sealCode": "555" } ], "arrivalCarrierType": "Truck" }, { "latestSubmissionStatus": { "action": "Create", "success": true }, "containerNumber": "CDPU3736997", "isoTypeCode": "2232", "flexiTank": false, "commodityCode": "0201", "isNonOperatingReefer": false, "refrigeration": { "isFantainer": false, "requiredTemperature": -5.0 }, "cargoWeightKg": 28000.0, "totalWeightKg": 30000.0, "containerSeals": [ { "sealType": "Shipper", "sealCode": "555" } ], "arrivalCarrierType": "Truck" } ] }


Cancelling an Export Pre-Advice

This operation cancels one or more containers in an export pre-advice. The export pre-advice is identified through the combination of a partner port code and a user reference.

Example

Containers to be cancelled from an export pre-advice are specified in the request payload of the delete action, as in this example.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 DELETE https://apitest.portconnect.io/v1/export-preadvices HTTP/1.1 Host: apitest.portconnect.io Content-Type: application/json Ocp-Apim-Subscription-Key: •••••••••••••••••••••••••••••••• { "header": { "partnerPortCode": "NZTRG", "userReference": "POT_TEST1" }, "containers": [ { "containerNumber": "CONU1234560" } ] }

Validation

Response

Success will result in a return code of 204 No Content.

Any errors in the request payload will result in a return code of 400 Bad request.  Further information will be supplied in the message payload.


Shipping Line Endpoints

PortConnect offers the following end points exclusively for the use of shipping lines.  Shipping line developers will need to contact our user support team to have access to these endpoints.   PortConnect associates an API user id with a specific line operator, so that storage pre-advice and booking api calls are associated with the correct shipping line.   It isn't possible to send or retrieve information in relation to other shipping lines.

Storage Pre-Advice (Ports of Auckland Only)

Shipping lines have the ability to pre-advise the arrival of storage containers to the LINK facility at the Ports of Auckland via this end point.  Containers cannot be gated in to the LINK facility unless they have been pre-advised in advance.

Import containers where the LINK facility has been specified by the shipping line as the return depot will automatically have a pre-advice generate for them at gate out.  This applies to import containers at both Ports of Auckland and Port of Tauranga, including associated inland ports.

Storage pre-advice should be submitted for the LINK facility when:

  1. An import has been gated out where an empty return depot other than LINK was specified or;

  2. An import has been gated out from a port other the Ports of Auckland or Port of Tauranga

Submitting a Storage Pre-Advice

A storage pre-advice can be submitted by posting to the lines/storage-pre-advices endpoint.

Example

Storage pre-advice submit
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 POST https://api.portconnect.io/lines/v1/storage-pre-advices HTTP/1.1 Host: api.portconnect.io Content-Type: application/json Ocp-Apim-Subscription-Key: •••••••••••••••••••••••••••••••• { "portCode": "NZAKL", "containers": [ { "containerNumber": "MSKU1512500", "containerIsoTypeCode": "4510" } ], "receiveLocation": "LNK" }

Validation

At this time the only supported value for portCode is "NZAKL", and the only supported value for receiveLocation is "LNK"

Response

Success will result in a return code of 201 Created.

Any errors will result in a return code of 400 Bad request.  Further information will be supplied in the message payload.

Bookings

Container bookings are used by PortConnect to validate the creation of export pre-advice messages.

Bookings have traditionally been supplied via EDIFACT messages such as COPARN.  PortConnect has created a set of endpoints that allows shipping lines to submit, retrieve and delete bookings from the PortConnect system.

Submit a Booking

A booking consists of top level booking information and one or more booking items.   Each booking item can optionally have hazardous and conditioning information. 

Example

Submit a Booking
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 POST https://api.portconnect.io/lines/v1/bookings HTTP/1.1 Host: api.portconnect.io Content-Type: application/json Ocp-Apim-Subscription-Key: •••••••••••••••••••••••••••••••• { "bookingNbr": "0AKL005396", "partnerPortCode": "NZTRG", "vesselVisit": { "vesselName": "BROTONNE BRIDGE", "vesselIMO": "9486116", "vesselCallSign": "", "vesselVoyageNbr": "010N", "vesselReference": "ROT010N" }, "msgReferenceNbr": "132576", "shipperName": "BOLLORE LOGISTICS NEW ZEALAND LTD", "consigneeName": "", "loadPortCode": "NZTRG", "dischargePortCode": "PFPPT", "finalDestinationPortCode": "PFPPT", "originPortCode": null, "bookingCategoryCode": "Export", "items": [{ "isoTypeCode": "2232", "quantity": 1.0, "bookingStatus": "FCL", "grossWeightKg": 14148.0, "commodityDesc": "FOOD:(NOS,CHILLED)", "temperatureRequired": 2.0, "oversizeFrontCm": null, "oversizeBackCm": null, "oversizeLeftCm": null, "oversizeRightCm": null, "oversizeTopCm": null, "hazards": [{ "unHazardNumber": "1950", "imdgClass": "2.2" } ], "conditioning": { "cO2Required": null, "o2Required": null, "humidityRequired": null, "ventRequired": 25.0, "ventRequiredUnit": "FlowM3PerHour" } } ] }

Validation

The following validation rules apply:

  • partnerPortCode must be one of NZAKL, NZTRG, NZTIU or NZLYT

  • vesselVisit must contain a minimum of vesselName and vesselVoyageNbr

  • valid UN port codes must be used

  • at least one booking item must be supplied

Response

Success will result in a return code of 201 Created.

Any errors will result in a return code of 400 Bad request.  Further information will be supplied in the message payload.

Retrieve a Booking

A booking can be retrieved by sending a get request. 

Example

The following example retrieves the booking above:

Retrieve a booking
1 https://api.portconnect.io/lines/v1/bookings/0AKL005396

Response

Success will result in a return code of 200 Ok.

A return code of 200 ok will also result if a booking is not found for the line operator, or if the booking has been cancelled.

Cancel a Booking

A booking can be cancelled in the PortConnect system by sending a delete request with an empty request body to the bookings end point, specifying the booking you want to delete.

Example

Cancel a Booking
1 DELETE https://apitest.portconnect.co.nz/v1/bookings/0AKL005396/HSUD

Response

A return code of 204 indicates the subscription has been cancelled successfully.

Resources


Postman

To assist with testing, we have created a set of Postman collections and an environment file, contained in PortConnectAPIPostmanTests20190510.zip

Setting Up

To use the tests in Postman:

  • Download the zip file and extract the three collection files and the environment file.

  • Import the files into Postman.

You should now see the following tests visible in Postman:

Now enter your subscription key obtained from the developer portal, and you are good to go:

Rate Limit

Trial Subscription

Limited to 120 calls to any endpoint within 60 seconds and 100 API calls to any end point within a 24 hour period.

Full Access Subscription
Limited to 240 calls to any endpoint within 60 seconds. Overall cap of 10,000 calls in a 24 hour period.



Pricing

A free trial subscription is available for 3-months. To register interest in a trial or for a full access subscription, please contact PortConnect at info@portconnect.co.nz

Scheduled vessels

  • $0.05NZD per call if not subscribed to Track & Trace

  • Free for Subscribed Track & Trace users

Container Visits

  • $0.05NZD per container/per call (max 10 containers per call) when searching containers directly.

Container Event Subscriptions

  • $0.20NZD per event update (Notification) sent*

  • Includes 1 free callback to the container visit URL to retrieve standing container data (provided in the callback payload).

*High volume users may qualify for preferred customer discounts.


Terms & Conditions
Users must be subscribed to Track & Trace for all API services.