Apm

Provider Information:

Id	apm
Type	terminal
Trace Type	API
Credentials	Uses client_id and client_secret and it is Envase based
Limits	Maximum number of containers per request is 50
Status	completed
Doc Status	draft
Doc Version	1

URLs:

Type	URL	Environment
Request	https://api.apmterminals.com/	DEV/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 access token request.

POST https://api.apmterminals.com/oauth/client_credential/accesstoken?grant_type=client_credentials

Note

This request needs authorization info of client_id and client_secret

Query Containers Request

Query containers using the request by adding the access token from the previous request in the headers as following.

Authorization: Bearer <Access Token>

GET https://api.apmterminals.com/import-availability?assetId={ContainerNumbers}&facilityCode={TerminalCode}

Apm API supports 3 terminals, they all use the same exact api and work by the same flow, the only thing that distinguish between them is the facility code in the querying request and it goes by the following.

Terminal Name	Facility Code
Los Angels terminal	USLAX
Port Elizabeth Terminal	USNWK
Mobile Terminal	USMOB
South Florida Container Terminal Miami	USMIA

Note

Container numbers in the request should be separated with commas.

Responses

Access Token Request Response

We only use the access_token from this payload.

{
    "refresh_token_expires_in": "0",
    "api_product_list": "[Import Availability - Sandbox, Export Booking Enquiry, Container Event History, Container Event History - Sandbox, Import Availability, Export Booking Enquiry - Sandbox, API Store Vessel Visits, Vessel Visits - Sandbox]",
    "api_product_list_json": [
            "Import Availability - Sandbox",
            "Export Booking Enquiry",
            "Container Event History",
            "Container Event History - Sandbox",
            "Import Availability",
            "Export Booking Enquiry - Sandbox",
            "API Store Vessel Visits",
            "Vessel Visits - Sandbox"
    ],
    "organization_name": "<organization_name>",
    "developer.email": "<developer@envasetechnologies.com>",
    "token_type": "BearerToken",
    "issued_at": "1634218637287",
    "client_id": "<client_id>",
    "access_token": "<access_token>",
    "application_name": "<application_name>",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"
}

Query Containers Request Response

ETA and Outgated Events Response

{
    "containerId": "MRKU0460988",
    "billOfLading": 268075460,
    "readyForDelivery": "false",
    "containerState": "DEPARTED",
    "dischargeDateTimeLocal": "2021-09-16T15:00:14-04:00",
    "yardLocation": "COMMUNITY - OUT",
    "containerHolds": {},
    "storagePaidThroughDate": "",
    "demurrageOwed": {},
    "sizeTypeHeight": "40/GP/86",
    "containerIsoCode": "42G1",
    "containerGrossWeightKilos": 6888,
    "containerGrossWeightPounds": 15185,
    "hazardous": {},
    "facilityOutDateTimeLocal": "2021-09-27T09:57:54-04:00",
    "vesselName": "GUNHILDE MAERSK",
    "vesselEtaDateTimeLocal": "2021-09-16T08:00:00-04:00",
    "shippingLine": "MAE",
    "appointment": "true",
    "appointmentDateTimeLocal": "2021-09-27T09:00:00-04:00"
}

Data Mapping:

Property	Source Property	Description
container_number	containerId	The container reference number.
steamshipBL	billOfLading	The lading number for the container.
carrier.type
carrier.steamshipLine	shippingLine	The scac for the carrier.
carrier.vessel	vesselName	The vessel id.
destination.name		Name of the location according to the provided facility code and it would be one of the terminal codes illustrated earlier
destination.type		This is a static value represents where the event happens and it is set to ‘terminal’.
event[n].code		Represents an ETA event and it is set to ‘eta’. Represents an Outgated event and it is set to ‘outgated’.
event[n].date		Date and time when this event was stored and it is value is always set to the current date time.
event[n].location.type		This is a static value represents where the event happens and it is set to ‘terminal’.
event[n].location.name		Name of the location according to the provided facility code and it would be one of the terminal codes illustrated earlier.
event[n].data.eta	vesselEtaDateTimeLocal	Date of the ETA event.
event[n].data.outgated	facilityOutDateTimeLocal	Date of the Outgated event.
event[n].data.outgate_confirmed		Part of the outgate event, and it is a static value with ‘True’ which represents that the terminal provides outgate information.

Grounded, Lfd, and Released Events Response

{
    "containerId": "MSDU4114681",
    "billOfLading": "X0923441",
    "readyForDelivery": "true",
    "containerState": "YARD",
    "dischargeDateTimeLocal": "2021-09-26T23:43:04-07:00",
    "yardLocation": "Yard Grounded (F0606F3)",
    "containerHolds": {},
    "storagePaidThroughDate": "2021-10-26T00:00:00",
    "demurrageOwed": {},
    "sizeTypeHeight": "40/GP/86",
    "containerIsoCode": 4310,
    "containerGrossWeightKilos": 15850,
    "containerGrossWeightPounds": 34943,
    "hazardous": {},
    "facilityOutDateTimeLocal": "",
    "vesselName": "MSC ARIANE",
    "vesselEtaDateTimeLocal": "2021-09-19T08:00:00-07:00",
    "shippingLine": "MSC",
    "appointment": "true",
    "appointmentDateTimeLocal": "2021-10-14T20:00:00-07:00"
}

Data Mapping:

Property	Source Property	Description
carrier.type		It is value is empty here because the container is not outgated.
event[n].code		Set to ‘grounded’ to represent a Grounded event when containerState is ‘Yard’ Set to ‘released’ to represent a Release event. Set to ‘lfd’ to represent a Lfd event.
event[n].date		Date and time when this event was stored and it is value is always set to the current date time.
event[n].location.type		This is a static value represents where the event happens and it is set to ‘terminal’.
event[n].location.name		Name of the location according to the provided facility code and it would be one of the terminal codes illustrated earlier.
event[n].data.grounded	dischargeDateTimeLocal	Part of the Grounded event and it is the date of the Grounded event.
event[n].data.released		Part of the Release event, it is always empty as APM don’t provide a release_date.
event[n].data.lfd	storagePaidThroughDate	Part of the Lfd event and it is the lfd for the container.

Custom TMF and Line Hold Events Response

{
    "containerId": "MSDU7219243",
    "billOfLading": "V3960568",
    "readyForDelivery": "false",
    "containerState": "INBOUND",
    "dischargeDateTimeLocal": "",
    "yardLocation": "V-E2O137S-620574",
    "containerHolds": "CUSTOMS,,LINE,TMF",
    "storagePaidThroughDate": "",
    "demurrageOwed": {},
    "sizeTypeHeight": "40/GP/96",
    "containerIsoCode": 4510,
    "containerGrossWeightKilos": 11343,
    "containerGrossWeightPounds": 25007,
    "hazardous": {},
    "facilityOutDateTimeLocal": "",
    "vesselName": "MAERSK ESMERALDAS",
    "vesselEtaDateTimeLocal": "2021-10-18T08:00:00-07:00",
    "shippingLine": "MSC",
    "appointment": "false",
    "appointmentDateTimeLocal": ""
}

Data Mapping:

Property	Source Property	Description
event[n].code		This is a static value set to ‘hold’ represents that a hold exists.
event[n].date		Date and time when this event was stored and it is value is always set to the current date time.
event[n].location.name		Name of the location according to the provided facility code and it would be of the terminal codes illustrated earlier’.
event[n].location.type		This is a static value represents where the event happens and it is set to ‘terminal’.
event[n].data.hold_type		Set to ‘customs’ to represents a Customs Hold event. Set to ‘tmf’ to represents a Tmf Hold event. Set to ‘line’ to represents a Line Hold event.

Unauthorized Response

{
    "code": "401",
    "message": "Unauthorized",
    "debugMessage": "Failed to Authenticate, invalid access token"
}

Not Found Response

{
    "AssetName": "ZCSU8614480",
    "message": "Asset Details Not Found"
}

Todo

Describe response for:

• Usda Hold Event.

• Ctf Hold Event.