Skip to content
Data Services
/
/
Retrieve Information Abou...

Data Services API (v1)

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.
Download OpenAPI description
swagger.json
swagger.yaml
Languages
Servers
Mock server
https://developer.cargosprint.com/_mock/dataservices/swagger
Server
https://developer.cargosprint.com/api

TerminalMetrics

Operations

Retrieve Information About Terminals

Request

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.

Security
apikey
Path
versionstringrequired
curl -i -X GET \
  'https://developer.cargosprint.com/_mock/dataservices/swagger/terminalmetrics/v{version}/terminals' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

terminals retrieved

Bodyapplication/json
terminalsArray of objects or null(TerminalMoveTypeDetail)
Response
application/json
{
  "terminals": [
    { … }
  ]
}

Retrieve Metrics About Appointment Availability

Request

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.

Security
apikey
Path
terminal_idstring(uuid)required

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.

versionstringrequired
curl -i -X GET \
  'https://developer.cargosprint.com/_mock/dataservices/swagger/terminalmetrics/v{version}/terminals/{terminal_id}/apptavailability' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

appointments by specific terminal ID retrieved

Bodyapplication/json
appointmentsArray of objects or null(DataMetricsV2DTO)
Response
application/json
{
  "appointments": [
    { … }
  ]
}

Retrieve Information About Terminal Dwell Statistics

Request

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.

Security
apikey
Path
terminal_idstring(uuid)required

terminal GUID(terminal_id) retrieved from the terminal API call

versionstringrequired
Query
start_datestring(date-time)required

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

end_datestring(date-time)required

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

dwell_optionstringrequired
  • 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_typestring
  • 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.

curl -i -X GET \
  'https://developer.cargosprint.com/_mock/dataservices/swagger/terminalmetrics/v{version}/terminals/{terminal_id}/containerdwelltime?start_date=2019-08-24T14%3A15%3A22Z&end_date=2019-08-24T14%3A15%3A22Z&dwell_option=string&trade_type=string' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

Information about terminal dwell statistics retrieved

Bodyapplication/json
terminal_idstring(uuid)

The terminal ID refers to the unique identifier of the terminal for which the dwell time is being calculated.

start_dttmstring(date-time)
end_dttmstring(date-time)

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

container_countinteger(int32)

Number of containers counted in dwell aggregation

avg_dwell_timenumber(double)

Average dwell time in hours

teunumber(double)

Total TEU of all containers matching search criteria

date_aggregated_dttmstring or null(date-time)

Date represents last modification date of records

Response
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.1,
  "teu": 0.1,
  "date_aggregated_dttm": "2019-08-24T14:15:22Z"
}

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

Request

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

Security
apikey
Path
terminal_idstring(uuid)required

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

versionstringrequired
Query
start_datestring(date-time)required

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

end_datestring(date-time)required

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

scac_cdstring

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

user_idstring(uuid)

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

curl -i -X GET \
  'https://developer.cargosprint.com/_mock/dataservices/swagger/terminalmetrics/v{version}/terminals/{terminal_id}/apptperformance?start_date=2019-08-24T14%3A15%3A22Z&end_date=2019-08-24T14%3A15%3A22Z&scac_cd=string&user_id=497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

Appointment performance data retrieved successfully.

Bodyapplication/json
date_aggregated_dttmstring(date-time)
terminal_cdstring or null
terminal_namestring or null
terminal_idstring or null
scac_cdstring or null
user_idstring or null(uuid)
appointmentsArray of objects or null(AppointmentCounts)
start_dttmstring or null
end_dttmstring or null
Response
application/json
{
  "date_aggregated_dttm": "2019-08-24T14:15:22Z",
  "terminal_cd": "string",
  "terminal_name": "string",
  "terminal_id": "string",
  "scac_cd": "string",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  "appointments": [
    { … }
  ],
  "start_dttm": "string",
  "end_dttm": "string"
}