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.

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 out after this date/time in dwell aggregation

end_date
required
string <date-time>

Include all containers discharged out prior to this date/time in dwell aggregation

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.
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
{
  • "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"
}