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. .. code-block:: shell 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. .. code-block:: shell 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. .. code-block:: Authorization: Bearer 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. .. code-block:: json [ { "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. .. code-block:: json { "userName": "", "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 .. code-block:: json { "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 .. code-block:: json { "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 .. code-block:: 401 Unauthorized If **siteId** is not passed in the request, It returns the following response. Returned status code: 400 Bad Request .. code-block:: json { "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 .. code-block:: [ { "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 .. code-block:: json [ { "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 .. code-block:: shell GET https://tosservice-api.portsamerica.com:9001/api/GateActivity/GateTransaction **headers** should be as following. .. code-block:: Authorization: Bearer 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. .. code-block:: json { "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. .. code-block:: json [ { "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 .. code-block:: json { "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 .. code-block:: json { "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 .. code-block:: json [ { "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 || - Arrived event is created if availability = "Yes" | || || || - Grounded event is created if discharge_time | || || || has a datetime value | || || last_free_day || - Released event is created If last_free_day has | || || || date and hold_information is empty | || || Outgated Endpoint || - 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: json [ { "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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: json [ { "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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: json [ { "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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: json [ { "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. .. code-block:: json [ { "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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: json [ { "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. | +------------------------+---------------------------+----------------------------------------------+