Ports America

Provider Information:

Id	ports_america
Type	terminal
Trace Type	API
Credentials	Uses user and password and it is Envase based
Limits	Maximum number of containers per request is 50 No limitations on generating number of tokens
Status	development
Doc Status	draft
Doc Version	1

URLs:

Type	URL	Environment
Request	https://tosservice-api.portsamerica.com:9001	PRD
Request	https://tosserviceuat-api.portsamerica.com:9001	STG/PRD

Sites:

Name	Site Id	Description
name	ern	the description

Request

Access Token Request

Querying containers requires an access token, so the first step is to get an access token using the following request.

POST https://tosservice-api.portsamerica.com:9001/api/Auth/GetToken

Note

This request needs in body: username and password.

Query Containers Request

Query containers using the following request by adding the access token from the previous request and site_id in following request.

GET https://tosservice-api.portsamerica.com:9001/api/ImportContainer/ContainerAvailability

Site ids goes as follow:

Site	Site Id
M.I.T. Seagirt Marine Terminal	SGT_BAL
OCT (Olympic Container Terminal)	OCT
PNCT (Port Newark Container Terminal)	PNCT_NJ
West Basin	WBCT_LA

headers should be as following.

Authorization: Bearer <Access Token>
SiteId: WBCT_LA

Note

For tracing westbasin containers the SiteId should be : WBCT_LA

body should be as following.

Then we need to pass the containers in body as following.

[
    {
        "containerNumber": "TGBU8592350"
    },
    {
        "containerNumber": "TCNU7889359"
    }
]

Note

Container numbers should follow the same structure as above.

Responses

Access Token Request Response

Returned status code: 200 OK

We only use the access_token from this payload.

{
    "userName": "<username that was sent in body>",
    "token": "<access token>"
}

Unauthorized Response

If credentials of username and password are expired or they are invalid then the following response is returned.

Returned status code: 400 Bad Request

{
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
        "DataError": [
            "The user name or password is incorrect."
        ]
    }
}

If credentials of username and password are not passed in request body then the following response is returned.

Returned status code: 415 Unsupported Media Type

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.13",
    "title": "Unsupported Media Type",
    "status": 415,
    "traceId": "|db2991d2-4b25c217d5688bcb.3.541a6422_"
}

Query Containers Request Response

Note

Token issues like token is expired, invalid token given or Authorication is not passed in headers

If token has issues, It returns with the following response.

Returned status code: 401 Unauthorized

401 Unauthorized

If siteId is not passed in the request, It returns the following response.

Returned status code: 400 Bad Request

{
    "Type": null,
    "Title": null,
    "Status": 400,
    "Detail": "SiteId Parameter missing from the Request Header Or other exception happened.",
    "Instance": null,
    "Extensions": {}
}

If given containers were invalid containers like Test123456 or having valid container but not found like UMXU253714 it returns the following respnse.

Returned status code: 200 OK

[
    {
        "container_number": "TEST123456",
        "bill_of_lading_number": "",
        "deumrrage_amount": 0.0,
        "ResponseCode": 1,
        "ResponseCodeDescription": "No record found"
    }
]

If given containers were valid but one found (TCNU7889359) and the other is not found (UMXU253714), It returns the following response.

Returned status code: 200 OK

[
     {
         "container_number": "UMXU253714",
         "bill_of_lading_number": "",
         "deumrrage_amount": 0.0,
         "ResponseCode": 1,
         "ResponseCodeDescription": "No record found"
     },
     {
         "container_number": "TCNU7889359",
         "bill_of_lading_number": "",
         "availability": "Yes",
         "steamshipline_code": "COS",
         "hold_information": [
         {
             "hold_id": "Demurrage Hold"
         }
         ],
         "vessel_name": "YANTIAN",
         "voyage_number": "107E",
         "order_of_accessibility": "",
         "location": "TF6MS-638-L5(D)",
         "last_free_day": "20211101",
         "last_guarantee_date": "",
         "paid_through_date": "",
         "deumrrage_amount": 1265.0,
         "container_type": "ST",
         "container_length": "40",
         "container_height": "114",
         "container_iso_code": "44G0",
         "gross_weight": "20381",
         "hazardous": "No",
         "genset_required": "No",
         "current_state": "",
         "next_move": "",
         "ResponseCode": 0,
         "ResponseCodeDescription": "Success"
     }
 ]

Outgated Event Request Response

To get inforamtion about the container events, A request has to be sent to the given url with headers that has Authorization and SiteId and containers in body.

Container Event status endpoint

GET https://tosservice-api.portsamerica.com:9001/api/GateActivity/GateTransaction

headers should be as following.

Authorization: Bearer <Access Token>
SiteId: WBCT_LA

Note

For tracing westbasin containers the SiteId should be : WBCT_LA

body should be as following.

Then we need to pass the containers in body as following.

{
    "containerNumbers": ["BSIU9368541","GLDU9379447"],
    "truckingCompanyCode": "PFCH",
    "startDate": "2021-11-12T23:45:56.406Z",
    "endDate": "2021-12-12T00:00:00"
}

Note

containerNumbers (required) should follow the same structure as above.
truckingCompanyCode (required) should represent the company that has the container.
startDate, endDate (optional) should represents the start and end dates for getting container events inforamtion considering given start and end dates

Response if body request has right data

Returned status code: 200 OK

Note

Result represents two containers but It shows all the status for the two given containers. And that is why it returns with three results.

[
    {
        "container_number": "BSIU9368541",
        "move_type": "Empty In",
        "in_gate_time": "2019-08-19T09:59:22",
        "out_gate_time": null,
        "container_type": "Standard",
        "container_length": "40",
        "container_height": "114",
        "steamshipline_code": "ONE",
        "chassis_number": "YMLZ4842262",
        "chassis_length": "40",
        "reference_number": null,
        "trucking_company_name": "A AND K TRUCKING LLC"
    },
    {
        "container_number": "BSIU9368541",
        "move_type": "Full Out",
        "in_gate_time": null,
        "out_gate_time": "2019-08-13T19:16:40",
        "container_type": "Standard",
        "container_length": "40",
        "container_height": "114",
        "steamshipline_code": "ONE",
        "chassis_number": "YMLZ4842262",
        "chassis_length": "40",
        "reference_number": "ONEYHPHV09927900",
        "trucking_company_name": "A AND K TRUCKING LLC"
    },
    {
        "container_number": "GLDU9379447",
        "move_type": "Empty In",
        "in_gate_time": "2019-08-14T12:28:56",
        "out_gate_time": null,
        "container_type": "Standard",
        "container_length": "20",
        "container_height": "102",
        "steamshipline_code": "ONE",
        "chassis_number": "FHCZ026571",
        "chassis_length": "20",
        "reference_number": null,
        "trucking_company_name": "A AND K TRUCKING LLC"
    }
]

Response if body is missing one of the required fields (containerNumbers, truckingCompanyCode).

If containerNumber was not passed.

Returned status code: 400 Bad Request

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "|db29943e-4b25c217d5688bcb.3.d9a8d5d2_",
    "errors": {
        "ContainerNumbers": [
            "The ContainerNumbers field is required."
        ]
    }
}

If truckingCompanyCode was not passed.

Returned status code: 400 Bad Request

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "|db299438-4b25c217d5688bcb.3.d9a8d5d1_",
    "errors": {
        "TruckingCompanyCode": [
            "The TruckingCompanyCode field is required."
        ]
    }
}

If passing all required fields but truckingCompanyCode has invalid code or trucking company does not have the containers yet.

Returned status code: 200 OK

[
    {
        "container_number": "BSIU9368541",
        "ResponseCode": 1,
        "ResponseCodeDescription": "No record found"
    },
    {
        "container_number": "GLDU9379447",
        "ResponseCode": 1,
        "ResponseCodeDescription": "No record found"
    }
]

Data Mapping:

Property	Source Property	Description
container_number	container_number	The container reference number
steamshipBL	bill_of_lading_number	Bill of lading
carrier.vessel	vessel_name	Carrier vessel number
carrier.voyage	voyage_number	Carrier Voyage number
event[n].code	availability last_free_day Outgated Endpoint	- Arrived event is created if availability = “Yes” - Grounded event is created if discharge_time has a datetime value - Released event is created If last_free_day has date and hold_information is empty - Outgated event is created if out_gate_time has datetime and move_type must be “Full Out”
event[n].location.lot	location	Lot of the location and possible values are Yard, Inland, On ship, Community
event[n].location.type	Default	Terminal as ports america is Terminal
event[n].date	Default	Today date is a default date

Arrived Event Response

[
    {
        "container_number": "WHSU5659471",
        "bill_of_lading_number": "",
        "availability": "Yes",
        "steamshipline_code": "WHL",
        "hold_information": [],
        "vessel_name": "JEJU ISLAND",
        "voyage_number": "E008",
        "order_of_accessibility": "",
        "location": "NN6-606-D1(D)",
        "last_free_day": "20211110",
        "last_guarantee_date": "",
        "paid_through_date": "",
        "deumrrage_amount": 0.0,
        "container_type": "ST",
        "container_length": "40",
        "container_height": "114",
        "container_iso_code": "44G0",
        "gross_weight": "34392",
        "hazardous": "No",
        "genset_required": "No",
        "current_state": "",
        "next_move": "",
        "ResponseCode": 0,
        "ResponseCodeDescription": "Success"
    }
]

Arrived Event Data Mapping:

Property	Source Property	Description
event[n].code	availability	Arrived event is created if availability = “Yes”
event[n].location.lot	location	Lot of the location and possible values are Yard, Inland, On ship, Community
event[n].location.name	Default	Site id sent on the request
event[n].location.type	Default	Terminal as ports america is Terminal
event[n].date	Default	Today date is a default date
event[n].data.arrived	Default	Empty string as api does not provide a date

Grounded Event Response

[
    {
        "container_number": "WHSU5659471",
        "bill_of_lading_number": "",
        "availability": "Yes",
        "steamshipline_code": "WHL",
        "hold_information": [],
        "vessel_name": "JEJU ISLAND",
        "voyage_number": "E008",
        "order_of_accessibility": "",
        "location": "NN6-606-D1(D)",
        "last_free_day": "20211110",
        "last_guarantee_date": "",
        "paid_through_date": "",
        "deumrrage_amount": 0.0,
        "container_type": "ST",
        "container_length": "40",
        "container_height": "114",
        "container_iso_code": "44G0",
        "gross_weight": "34392",
        "hazardous": "No",
        "genset_required": "No",
        "current_state": "",
        "next_move": "",
        "ResponseCode": 0,
        "ResponseCodeDescription": "Success"
    }
]

Grounded Event Data Mapping:

Property	Source Property	Description
event[n].code	availability	Grounded event is created if discharge_time has value
event[n].location.lot	location	Lot of the location and possible values are Yard, Inland, On ship, Community.
event[n].location.name	Default	Site id sent on the request
event[n].location.type	Default	Terminal as ports america is Terminal
event[n].date	Default	Today date is a default date
event[n].data.grounded	Default	Value is set with discharge_time value

Lfd Event Response

 [
     {
      "container_number": "WHSU5007811",
      "bill_of_lading_number": "",
      "availability": "Yes",
      "steamshipline_code": "WHL",
      "hold_information": [],
      "vessel_name": "JEJU ISLAND",
      "voyage_number": "E008",
      "order_of_accessibility": "",
      "location": "NN6-620-B3(D)",
      "last_free_day": "20211110",
      "last_guarantee_date": "",
      "paid_through_date": "",
      "deumrrage_amount": 0.0,
      "container_type": "ST",
      "container_length": "40",
      "container_height": "114",
      "container_iso_code": "44G0",
      "gross_weight": "51587",
      "hazardous": "No",
      "genset_required": "No",
      "current_state": "",
      "next_move": "",
      "ResponseCode": 0,
      "ResponseCodeDescription": "Success"
  }
]

Lfd Event Data Mapping:

Property	Source Property	Description
event[n].code	last_free_day	Lfd event is created If last_free_day has date and hold_information is empty
event[n].location.lot	location	Lot of the location and possible values are Yard, Inland, On ship, Community
event[n].location.name	Default	Site id sent on the request
event[n].location.type	Default	Terminal as ports america is Terminal
event[n].date	Default	Today date is a default date
event[n].data.lfd	last_free_day	Last free date for container

Released Event Response

 [
     {
      "container_number": "WHSU5007811",
      "bill_of_lading_number": "",
      "availability": "Yes",
      "steamshipline_code": "WHL",
      "hold_information": [],
      "vessel_name": "JEJU ISLAND",
      "voyage_number": "E008",
      "order_of_accessibility": "",
      "location": "NN6-620-B3(D)",
      "last_free_day": "20211110",
      "last_guarantee_date": "",
      "paid_through_date": "",
      "deumrrage_amount": 0.0,
      "container_type": "ST",
      "container_length": "40",
      "container_height": "114",
      "container_iso_code": "44G0",
      "gross_weight": "51587",
      "hazardous": "No",
      "genset_required": "No",
      "current_state": "",
      "next_move": "",
      "ResponseCode": 0,
      "ResponseCodeDescription": "Success"
  }
]

Released Event Data Mapping:

Property	Source Property	Description
event[n].code	last_free_day	Released event is created If last_free_day has date and hold_information is empty
event[n].location.lot	location	Lot of the location and possible values are Yard, Inland, On ship, Community
event[n].location.name	Default	Site id sent on the request
event[n].location.type	Default	Terminal as ports america is Terminal
event[n].date	Default	Today date is a default date
event[n].data.released	Default	Empty string as api does not provide a date

Outgated Event Response

Note

Result represnts two containers (GLDU9379447, MOTU0791441) but It shows all the status for the two given container. And that is why it returns with three results.

[
    {
        "container_number": "GLDU9379447",
        "move_type": "Empty In",
        "in_gate_time": "2019-08-14T12:28:56",
        "out_gate_time": null,
        "container_type": "Standard",
        "container_length": "20",
        "container_height": "102",
        "steamshipline_code": "ONE",
        "chassis_number": "FHCZ026571",
        "chassis_length": "20",
        "reference_number": null,
        "trucking_company_name": "A AND K TRUCKING LLC"
    },
    {
        "container_number": "GLDU9379447",
        "move_type": "Full Out",
        "in_gate_time": null,
        "out_gate_time": "2019-08-09T11:35:47",
        "container_type": "Standard",
        "container_length": "20",
        "container_height": "102",
        "steamshipline_code": "ONE",
        "chassis_number": "FHCZ026571",
        "chassis_length": "20",
        "reference_number": "ONEYSZPVA3497301",
        "trucking_company_name": "A AND K TRUCKING LLC"
    },
    {
        "container_number": "MOTU0791441",
        "move_type": "Full Out",
        "in_gate_time": null,
        "out_gate_time": "2019-06-26T17:07:27",
        "container_type": "Standard",
        "container_length": "40",
        "container_height": "114",
        "steamshipline_code": "ONE",
        "chassis_number": "FLXZ403339",
        "chassis_length": "40",
        "reference_number": "ONEYNB8BQ4993900",
        "trucking_company_name": "A AND K TRUCKING LLC"
    }
]

Outgated Event Data Mapping:

Property	Source Property	Description
event[n].code	Outgated Endpoint	Outgated event is created when out_gate_time has datetime and move_type must be “Full Out”
event[n].location.lot	location	Lot of the location and possible values are Yard, Inland, On ship, Community
event[n].location.name	Default	Site id sent on the request
event[n].location.type	Default	Terminal as ports america is Terminal
event[n].date	Default	Today date is a default date
event[n].data.outgated	out_gate_time	Empty string, API does not provide date
event[n].data.outgate_scac	trucking_company_name	Trucking company name that has the container
event[n].data.outgate_confirmed	Default	Value is set to True as it is an indicator for event as outgated or not

Hold Events Response

[
    {
        "container_number": "GLDU9379447",
        "bill_of_lading_number": "",
        "availability": "Yes",
        "steamshipline_code": "COS",
        "hold_information": [
            {
              "hold_id": "Demurrage Hold"
            },
            {
              "hold_id": "Customs Hold"
            },
            {
              "hold_id": "Line Hold"
            },
            {
              "hold_id": "CTF Hold"
            },
            {
              "hold_id": "TMF Hold"
            },
        ],
        "vessel_name": "YANTIAN",
        "voyage_number": "107E",
        "order_of_accessibility": "",
        "location": "TF6MS-638-L5(D)",
        "last_free_day": "20211101",
        "last_guarantee_date": "",
        "paid_through_date": "",
        "deumrrage_amount": 1265.0,
        "container_type": "ST",
        "container_length": "40",
        "container_height": "114",
        "container_iso_code": "44G0",
        "gross_weight": "20381",
        "hazardous": "No",
        "genset_required": "No",
        "current_state": "",
        "next_move": "",
        "ResponseCode": 0,
        "ResponseCodeDescription": "Success"
    }
]

Hold Events:

Property	Source Property	Description
event[n].code	Default	Hold as it is hold event
event[n].location.lot	location	Lot of the location and possible values are Yard, Inland, On ship, Community
event[n].location.name	Default	Site id sent on the request
event[n].location.type	Default	Terminal as ports america is Terminal
event[n].date	Default	Today date is a default date
event[n].holdType	hold_information.hold_id	HoldType can be: Ctf if CTF Hold. Custom if Custom Hold. Demurrage if Demurrage Hold. Line if Line Hold. Tmf if TMF Hold.
event[n].data.code	hold_information.hold_id	hold_id determine code and it can be: CTF Hold. Custom Hold. Demurrage Hold. Line Hold. TMF Hold.