eModal Data Services API (v1)

Download OpenAPI specification:Download

This document outlines instructions for retrieving various datasets from the eModal lakehouse for various ports and terminals. The data is made available via REST API calls for the following datasets:

  • Information about the available terminals for the port.
  • Appointment availability information in a specific terminal.
  • Aggregated container dwell statistics in a specific terminal.
  • Appointment performance metrics for a specific terminal.

TerminalMetrics

Retrieve Information About Terminals

This endpoint returns information about individual terminals including terminal name/code/ID, supported move types(pickup, drop off, etc.), and appointment type(slot vs pre-advice). This information is required to query specific terminal appointment availability or dwell statistics.

Securityapikey
Request
path Parameters
version
required
string
Responses
200

terminals retrieved

400

Bad request

401

Unauthorized

403

Forbidden

500

Server error occured

get/terminalmetrics/v{version}/terminals
Response samples
application/json
{
  • "terminals": [
    ]
}

Retrieve Metrics About Appointment Availability

This API endpoint returns appointment availability statistics for time slotted appointments. This API returns data only for the time slotted appointment move types and does not include pre-advice information as it is not applicable as an appointment availability statistic. The response will contain appointment availability data starting with the current date and 7 days into the future and contain a listing of available and booked appointments by move type and time slot for a specific terminal.

Securityapikey
Request
path Parameters
terminal_id
required
string <uuid>

The input is the terminal GUID received from the first API call and embed it along the URL to get the details of the specific terminal.

version
required
string
Responses
200

appointments by specific terminal ID retrieved

400

Bad request

401

Unauthorized

403

Forbidden

500

Server error occured

get/terminalmetrics/v{version}/terminals/{terminal_id}/apptavailability
Response samples
application/json
{
  • "appointments": [
    ]
}

Retrieve Information About Terminal Dwell Statistics

This API endpoint provides information about container dwell time in a specific terminal. The dwelling time is calculated as an average dwell within the specified date range. Dwell time is average time spent in hours on the terminal between containers discharge date and gate out date or from discharge to current dwell time on terminal.

Securityapikey
Request
path Parameters
terminal_id
required
string <uuid>

terminal GUID(terminal_id) retrieved from the terminal API call

version
required
string
query Parameters
start_date
required
string <date-time>

Include all containers discharged after this date/time in dwell aggregation(Format: yyyy-MM-ddTHH:mm:ss)

end_date
required
string <date-time>

Include all containers discharged prior to this date/time in dwell aggregation(Format: yyyy-MM-ddTHH:mm:ss)

dwell_option
required
string
  • on_terminal_only: Retrieve dwell statistics only for containers which are on terminal.
  • off_terminal_only: Retrieve dwell statistics only for containers that have already left the terminal.
  • all: Retrieve dwell statistics for all containers that are in yard inventory as well as containers that have already left the terminal.
trade_type
string
  • import: Retrieve dwell statistics only for containers with import trade type.
  • export: Retrieve dwell statistics only for containers with export trade type.

If trade type is empty, dwell statistics for all trade types (import and export) will be retrieved.

Responses
200

Information about terminal dwell statistics retrieved

400

Bad request

401

Unauthorized

403

Forbidden

500

Server error occured

get/terminalmetrics/v{version}/terminals/{terminal_id}/containerdwelltime
Response samples
application/json
{
  • "terminal_id": "1950b55f-ca16-4e1b-b652-2d6bf2615c40",
  • "start_dttm": "2019-08-24T14:15:22Z",
  • "end_dttm": "2019-08-24T14:15:22Z",
  • "container_count": 0,
  • "avg_dwell_time": 0,
  • "teu": 0,
  • "date_aggregated_dttm": "2019-08-24T14:15:22Z"
}

Retrieves appointment performance metrics for a specific terminal within a given date range.

This endpoint returns aggregated appointment performance data for the specified terminal and date range. The response includes appointment counts and related statistics.

Securityapikey
Request
path Parameters
terminal_id
required
string <uuid>

The unique identifier (GUID) of the terminal for which appointment performance is requested.

version
required
string
query Parameters
start_date
required
string <date-time>

The start date of the range for which appointment performance is to be retrieved (format: yyyy-MM-dd).

end_date
required
string <date-time>

The end date of the range for which appointment performance is to be retrieved (format: yyyy-MM-dd).

scac_cd
string

Optional. The Standard Carrier Alpha Code (SCAC) to filter appointments by carrier.

user_id
string <uuid>

Optional. The unique identifier (GUID) of the user to filter appointments by user.

Responses
200

Appointment performance data retrieved successfully.

400

Bad request, such as invalid terminal ID or date range.

401

Unauthorized

403

Forbidden

500

Server error occurred while processing the request.

get/terminalmetrics/v{version}/terminals/{terminal_id}/apptperformance
Response samples
application/json
{
  • "date_aggregared_dttm": {
    },
  • "terminal_cd": "string",
  • "terminal_name": "string",
  • "terminal_id": "string",
  • "scac_cd": "string",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "appointments": [
    ]
}