Skip to main content
Deutsch (Deutschland) Français (France) Italiano Polski

Search

search shadow

Articles in this section

Port Intelligence APIs

Rich Hellinga
Rich Hellinga
Updated

In this article

The Port Intelligence Product consists of one API.

The API is briefly described in the table below. The table includes a link to the API’s complete structure and sample code in both the North American (NA) Developer Portal and the European (EU) Developer Portal of the VOC.

Tip

For best results, before clicking any Developer Portal link, set your default browser to Firefox and sign in to the VOC.

API Name

Description

(NA) GET: Query for Port Intelligence

(EU) GET: Query for Port Intelligence

Based off the date of the query, retrieves a list of daily, weekly, and monthly metrics on parameters such as number of vessels approaching and various dwell time statistics in JSON or CSV format.

Customers use the Query for Port Intelligence API to retrieve port intelligence data in either JSON or CSV format.

Workflow: API Request & Sample API Response-JSON

Customers with advanced technology use the Query for Port Intelligence Data API to retrieve metrics in JSON format for up to 10 ports per Request:

  1. The Customer sends a Query for Port Intelligence Data API Request including up to 10 port location codes to project44. The example Request below includes two ports (Los Angeles (USLAX) and Hong Kong (HKHKG)), and it was sent on 2022-03-01:

    1 GET /api/v4/analytics/port-intelligence/summary?locodes=USLAX,HKHKG

  2. project44 returns a Query for Port Intelligence Data API Response to the Customer containing metrics for Los Angeles followed by metrics for Hong Kong. This code snippet is a sample of the data from the Port Los Angeles portion of that complete Response:

    1 {
2    "ports":[{
3            "portLocode": "USLAX",
4            "portName": "Los Angeles",
5            "anchorMonthly": [{
6                    "date": "2022-02-01",
7                    "p25": 0.27,
8                    "p50": 0.32,
9                    "p75": 1.3
10                },...
11            ],
12            "anchorWeekly": [ /* same format as anchorMonthly */ ],
13            "approachingDaily":[{
14                    "date": "2022-03-01",
15                    "vesselsApproaching": 59,
16                },...
17            ],
18            "berthingMonthly":[{
19                    "date": "2022-02-01",
20                    "p25": 2.7,
21                    "p50": 4.88,
22                    "p75": 7.23
23                }
24            ],
25            "berthingWeekly": [ /* same format as berthingMonthly */ ],
26            "dwellMonthly":[{
27                    "date": "2022-03-01",
28                    "podDischargeP25": 3.91,
29                    "podDischargeP50": 7.06,
30                    "podDischargeP75": 9.21,
31                    "polLoadP25": 16.42,
32                    "polLoadP50": 16.42,
33                    "polLoadP75": 16.42
34                 },...
35            ],
36            "dwellWeekly": [ /* same format as dwellMonthly */ ],
37        },...
38    ]
39 }

  3. The Customer either uses the information as-is or uses it as input into their own number-crunching system to make informed decisions on routing shipments.

Workflow: API Request & Sample API Response-CSV

Customers with less advanced technology can use the Query for Port Intelligence Data API preceded by an Accept line to retrieve metrics in CSV format for up to 10 ports per Request:

  1. The Customer sends the lines below (including up to 10 port location codes on the Query for Port Intelligence Request) to project44. The example Request below includes two ports (Los Angeles (USLAX) and Hong Kong (HKHKG)), and it was sent on 2022-03-01:

    1 Accept: text/csv
2 GET /api/v4/analytics/port-intelligence/summary/?locodes=USLAX,HKHKG

  2. project44 returns a Query for Port Intelligence Data API Response containing a line of Field names followed by lines of corresponding comma-separated data. This code snippet is a sample from that complete Response:

    1 locode,name,date,timespan,vesselsAnchoredP25,vesselsAnchoredP50,vesselsAnchoredP75,vesselsBerthingP25,vesselsBerthingP50,vesselsBerthingP75,vesselsApproaching,containerDwellP25,containerDwellP50,containerDwellP75,containerLoadP25,containerLoadP50,containerLoadP75
2 USLAX,"Los Angeles",2022-01-30,daily,,,,,,,72,,,,,,
3     <29 LINES FOR EACH OTHER DAY: 2022-01-31 & 2022-02-01 - 2022-02-28>
4 USLAX,"Los Angeles",2022-03-01,daily,,,,,,,59,,,,,,
5 USLAX,"Los Angeles",2021-03-01,monthly,0.51,5.76,10.76,2.5,4.96,7.51,,3,5.06,8.96,7.36,11.03,14.65
6     <11 LINES FOR EACH OTHER MONTH: 2021-04-01 - 2022-02-01>
7 USLAX,"Los Angeles",2022-03-01,monthly,,,,,,,,3.91,7.06,9.21,16.42,16.42,16.42
8 USLAX,"Los Angeles",2021-10-18,weekly,5.87,14.26,17.83,5.39,6.94,10.96,,2.55,4.88,11.02,7.5,11.34,16.88
9     <19 LINES FOR EACH OTHER WEEK: 2021-10-25 - 2022-02-21>
10 USLAX,"Los Angeles",2022-02-28,weekly,0.27,0.28,4.06,1.23,1.61,5.11,,3.52,5.04,8,8.24,9.88,13.65
11     <DUPLICATION OF LINES 2-10 FOR HONG KONG>

Response Field Descriptions

This table explains the Fields of both the JSON and CSV Query for Port Intelligence Data API Responses and shows how Sample CVS Response Line #5 above aligns with the table’s CVS Fields (which match those of Sample CVS Response Line #1).

 Metric

JSON Fields

(all names preceded by “ports.”)

CSV Fields

(in order of receipt)

Line #5

of CSV

Response

The unique UN/LOCODE port location code.

portLocode

locode

USLAX

The port name.

portName

name

“Los Angeles”

The date in ISO-8601 format associated with the metric provided.

metricTimespan.date

(e. g., dwellDaily.date)

date

2021-03-01

 The timespan for the data:

  • Daily (CSV: daily):

    • Up to 31 days of data, including the current day and any of the previous 30 with data. Each day has its own section (JSON) or line (CSV) in the Response.

    • A day runs from 00:00:00 to 23:59:59 in the port’s time zone.

  • Monthly (CVS: monthly):

    • Up to 13 months with data, including the current incomplete month and up to 11 previous months, has its own section (JSON) or line (CSV) in the Response.

    • The current incomplete month runs from its first day at 00:00:00 to its last complete day at 23:59:59 in the port’s time zone.

    • The past complete months run from their first day at 00:00:00 to their last at 23:59:59 in the port’s time zone.

  • Weekly (CVS: weekly):

    • Each complete week with data of the previous 20 has its own section (JSON) or line (CSV) in the Response.

    • A week runs from Monday 00:00:00 to Sunday 23:59:59 in the port’s time zone.

  • The project44 datastore lags real time by at least 24 hours.

  • Data is provided with respect to the date of the API request.

metricTimespan

(e. g., dwellDaily)

timespan

monthly

Vessel Anchor Dwell:

The time it takes a vessel to actually moor once it has arrived within 50 nmi of the port.

The number of days by which 25% of vessels completed this stage in this timespan.

anchorMonthly.p25

vesselsAnchoredP25

(when timespan = monthly)

0.51

The number of days by which 50% of vessels completed this stage in this timespan.

anchorMontly.p50

vesselsAnchoredP50

(when timespan = monthly)

5.76

The number of days by which 75% of vessels completed this stage in this timespan.

anchorMonthly.p75

vesselsAnchoredP75

(when timespan = monthly)

10.76

The number of days by which 25% of vessels completed this stage in this timespan.

anchorWeekly.p25

vesselsAnchoredP25

(when timespan = weekly)

The number of days by which 50% of vessels completed this stage in this timespan.

anchorWeekly.p50

vesselsAnchoredP50

(when timespan = weekly)

The number of days by which 75% of vessels completed this stage in this timespan.

anchorWeekly.p75

vesselsAnchoredP75

(when timespan = weekly)

Vessel Berthing Dwell:

The time a vessel spends inside the terminal being loaded or unloaded, measured from mooring time to unmooring time.

The number of days by which 25% of vessels completed this stage in this timespan.

berthingMonthly.p25

vesselsBerthingP25

(when timespan = monthly)

2.5

The number of days by which 50% of vessels completed this stage in this timespan.

berthingMonthly.p50

vesselsBerthingP50

(when timespan = monthly)

4.96

The number of days by which 75% of vessels completed this stage in this timespan.

berthingMonthly.p75

vesselsBerthingP75

(when timespan = monthly)

7.51

The number of days by which 25% of vessels completed this stage in this timespan.

berthingWeekly.p25

vesselsBerthingP25

(when timespan = weekly)

The number of days by which 50% of vessels completed this stage in this timespan.

berthingWeekly.p50

vesselsBerthingP50

(when timespan = weekly)

The number of days by which 75% of vessels completed this stage in this timespan.

berthingWeekly.p75

vesselsBerthingP75

(when timespan = weekly)

Daily Approaching Vessels:

The number of vessels having this port as their destination regardless of AIS ETA.

The number of vessels with this destination port.

approachingDaily.vesselsApproaching

vesselsApproaching

(when timespan = daily)

Container Discharge Dwell:

The time a container sits in the port of discharge before gate-out.

The number of days by which 25% of containers completed this stage in this timespan.

dwellMonthly.podDischargeP25

containerDwellP25

(when timespan = monthly)

3

The number of days by which 50% of containers completed this stage in this timespan.

dwellMonthly.podDischargeP50

containerDwellP50

(when timespan = monthly)

5.06

The number of days by which 75% of containers completed this stage in this timespan.

dwellMonthly.podDischargeP75

containerDwellP75

(when timespan = monthly)

8.96

The number of days by which 25% of containers completed this stage in this timespan.

dwellWeekly.podDischargeP25

containerDwellP25

(when timespan = weekly)

The number of days by which 50% of containers completed this stage in this timespan.

dwellWeekly.podDischargeP50

containerDwellP50

(when timespan = weekly)

The number of days by which 75% of containers completed this stage in this timespan.

dwellWeekly.podDischargeP75

containerDwellP75

(when timespan = weekly)

Container Loading Dwell:

The time a container sits in the port of loading between gate-in and being loaded on a vessel.

The number of days by which 25% of containers completed this stage in this timespan.

dwellMonthly.polLoadP25

containerLoadP25

(when timespan = monthly)

7.36

The number of days by which 50% of containers completed this stage in this timespan.

dwellMonthly.polLoadP50

containerLoadP50

(when timespan = monthly)

11.03

The number of days by which 75% of containers completed this stage in this timespan.

dwellMonthly.polLoadP75

containerLoadP75

(when timespan = monthly)

14.65

The number of days by which 25% of containers completed this stage in this timespan.

dwellWeekly.polLoadP25

containerLoadP25

(when timespan = weekly)

The number of days by which 50% of containers completed this stage in this timespan.

dwellWeekly.polLoadP50

containerLoadP50

(when timespan = weekly)

The number of days by which 75% of containers completed this stage in this timespan.

dwellWeekly.polLoadP75

containerLoadP75

(when timespan = weekly)

Related articles