API - FAQs

Owned by Chris Boxall
Last updated: 26 Sept, 2024
6 min read

What is an API?

API is the acronym for application programming interface — a software intermediary that allows two applications to talk to each other.

What APIs does PortConnect offer?

API Name

API Description

API Name

API Description

Container Visit API

A summary of details related to a container visit. B2B equivalent of searching a container on Track & Trace.

Vessel Schedule API

A summary of all Vessel Schedule information. B2B equivalent of searching the Vessel Schedule on the PortConnect website.

Container Visit Event API

Register interest in container visits and event types and then PortConnect will send you event information when those events occur.

Vessel schedule Event API

Register interest in vessel visits and event types and then PortConnect will send you event information when those events occur.

Export Pre-Advice API

Send pre-advice to PortConnect directly from your system rather than manually entering the data via our website.

What ports is the data available for?

  1. Port of Auckland

  2. Port of Tauranga

  3. Timaru Container Terminal

  4. Lyttelton Port Company

  5. Depots

 

What is the Container Visit and Container Visit Event combo?

For container data, most of our customers use a combination of the Container Visit Event API and the Container Visit API. Users subscribe to specific events and get informed when they happen then they call the Container Visit API to check any other details that may have changed against the container visit. Users who receive Events are entitled to one free call to the Container Visit API for each event they receive.

 

What Container event types are available?

A full list of event types is available here, Container Visit Event Types

 

What are the most commonly used event types?

Below is a summary of event types most commonly used,

Imports

Importers

Importers

Active

Cleared

Discharge

Available

Customs Release

MPI Release

LOP Release

LFT Changed

VBS Changed

Gate Out

Gate In (inland Port)

 

Exports

Exporters

Exporters

Active

Gate In

Load

 

Do events get updated?

Yes! Some events get recorded multiple times.

Event Type

Description

Event Type

Description

Gate In/Out

Gate events can occur across multiple facilities. Gate events include the specific facility location information.

Line Release, MPI Release, Customs Release, Available, Cleared

These events all have a corresponding Cancelled version that you must subscribe to separately. Clearances can be revoked or updated and PortConnect records a Cancelled type event when this occurs. Once the issue has been resolved then a new release event will be created with a new event time.

VBS Changed

As trucking companies plan and replan their jobs, VBS bookings may be cancelled and changed. This event will be sent each time a booking is changed.

LFT Changed

Last Free Times can change if containers are moving between facilities or if the port decides to provide extra free days due unexpected delays.

 

Vessel schedule events, other than Actual Arrival and Actual Departure, are often updated.

When can I use the container data APIs? When will container data be available?

Containers will only show up in the APIs when the containers have been created in the ports' systems. For Imports this occurs when the port loads the Baplie (aka the vessel manifest) and for exports this occurs when a pre-advice has been submitted. See the combination section).

How does the pricing work?

The full details of pricing is available here, https://www.portconnect.co.nz/#/content/pricing

High volume users may qualify for preferred customer discounts.

Container Visit API and Container Visit Event API discount

Users who receive Events are entitled to one free call to the Container Visit API for each event they receive. Most users subscribe to specific events then once they receive the event they call the Container Visit API to pick up additional container Visit details.

 

How do Container Visit Event subscriptions work?

Users create Subscriptions using a combination of Container, Category and Port. When PortConnect finds a container visit that matches a subscription then PortConnect starts sending the events that have been registered for.

E.g. a user subscribes to receive the Active event against Container XXX with a category of Import and a port of Port of Auckland. If/when an Import container called XXX is created in the Port of Auckland system then PortConnect will send the Active event.

Some container can change or move through different ports so PortConnect also provides the option for setting the port as ALL and PortConnect will send events for any matching Container/Category across any port.

e.g. a user subscribed to receive Load and Discharge events against Container YYY with a category of Domestic and a port of ALL. If when a container loads at Auckland and discharges in Lyttelton then two events will be sent. This can also be achieved by creating two subscriptions for the different ports.

 

What are the different container Categories?

  1. Import - Containers arriving from overseas

  2. Export - Containers departing overseas

  3. Domestic - Containers moving within NZ - This is based on the Load and Discharge ports.

  4. Tranship - Containers moving from one vessel to another vessel

  5. Storage - Empty containers returned to a depot or link facility

 

What is the typical flow of containers through the ports?

 

Imports

  1. Customs/MPI/Line release

  2. Container created via Baplie (Active)

  3. Cleared event recorded

  4. Discharge

  5. Available event recorded

  6. VBS obtained or Rail booked (rules vary by port)

  7. LFT set

  8. Gate Out of Seaport

  9. Gate in at Inland Port (Optional)

  10. LFT Changed (Optional)

  11. Gate out of inland port (Optional)

  12. Empty container returned to a depot (Depot Gate In)

 

Exports

  1. Container pre-advised (Active)

  2. CEDO applied

  3. VBS obtained

  4. Gate In at Inland Port (Optional)

  5. Gate Out of Inland Port (Optional)

  6. Gate In at Seaport

  7. Load

 

Are there any differences between ports or other details to consider?

Q

A

Q

A

When do containers get created?

Import containers are created when the port receives the Baplie (Vessel Manifest file) from the shipping line.

Export containers are created when the export pre-advice is submitted.

What happens when clearances and release messages are received before the container is active in the port’s system?

NZAKL, NZTRG, NZTIU - The clearances are stored until the import record is created. Once the import record is created, the clearances are recorded with the timestamp from when the messages arrived.

 

NZLYT - The clearances are stored until the import record is created. Once the import record is created, the clearances are recorded with the timestamp from when the container was created.

When can VBS bookings be made?

NZAKL

Imports - VBS bookings can be made once containers are cleared and before they are discharged.

Exports - VBS bookings can be made once containers have been pre-advised.

NZTRG

Imports - VBS bookings can only be made once containers are cleared and discharged.

Exports - VBS bookings can be made once containers have been pre-advised. Bookings can also be made by Booking Number.

 

Metroport

Imports - VBS bookings can only be made once containers are cleared and they have arrived at Metroport.

Exports - VBS bookings can be made once containers have been pre-advised.

 

NZLYT

Imports - VBS bookings can be made once containers are cleared and before they are discharged.

Exports - VBS bookings can be made once containers have been pre-advised.

 

City Depot

Imports - VBS bookings can only be made once containers are cleared and they have arrived at City Depot.

Exports - VBS bookings can be made once containers have been pre-advised.

How long back does Track & Trace History go?

NZAKL, NZTRG - Records go back to 2015.

NZTIU - Records go back to 2022

NZLYT - Records are currently only available via the Container Visit API which shows up to 1 year of historic data.

 

Where should we begin with an API integration?

  1. Send a link to our detailed technical documents to your developers/software provider and they can confirm if/how your system could process the APIs.

  2. Determine what data you are interested in processing into your system.

  3. Sign up for an API Key so you can test with the API. See our user-guide here, Creating an API account

  4. Once you have signed up for the API you can obtain an API Key and select a Product type - FULL Access or Trial. We recommend starting with Trail while testing and the product type can be updated once you are ready to go live.

  5. Once you have determined what data you want and your developers have read the documentation then PortConnect is available to answer any process or technical questions you might have. Send an email to info@portconnect.co.nz to get started.

 

As a software provider, can I apply for multiple API keys for my individual customers?

Yes. PortConnect bills based on the API key used to access the APIs. Software providers have the option to use a single API key and receive the bill related to all their customs or they can use multiple API keys and billing will be sent directly to the individual companies.

 

Are API keys associated with an organisation in PortConnect?

API keys do not need to be linked directly to a Trading Party in PortConnect but in the Container Visit Event API the Express Pin type events can only be sent to the party that obtained the Express PINs so the API key must be linked to receive the events. The linking will be done by PortConnect staff.

© PortConnect 2023