The History Dataset API from ShipFinder AIS Data API — 6 operation(s) for history dataset.
openapi: 3.2.0
info:
title: ShipFinder Global Maritime Data History Dataset API
description: 'REST/HTTP API for global AIS vessel tracking and maritime intelligence, organised into seven datasets: AIS (real-time vessel positioning, search, nearby, in-zone, flag), Voyage (port information, berthed/anchored vessels, expected arrivals), History (position tracks, ship-to-ship events, port-call records), Prediction (point-to-point and port-to-port route planning, ETA), Meteorology (tropical cyclones, tide gauge stations, marine weather), China Region Coastline Warnings, and Event (monitored fleet management, geofences and speed-alert subscriptions that drive push streams). All requests carry the API key as the "key" query parameter; all responses are JSON with a {status, msg, data} envelope where status 0 means success.
Assembled by API Evangelist from the per-endpoint OpenAPI 3.0.1 fragments ShipFinder publishes on docs.shipfinder.com. Operation content is the provider''s; API Evangelist added operationIds, servers, securitySchemes, dataset tags, externalDocs, and remapped the published "0" response key to "200" (see overlays/).'
version: 1.0.0
contact:
name: ShipFinder Support
email: support@elaneglobal.com
url: https://www.shipfinder.com/help-center
termsOfService: https://www.shipfinder.com/Home/TermsConditions
servers:
- url: https://api.elaneglobal.com
description: Production
security:
- apiKeyQuery: []
tags:
- name: History Dataset
paths:
/v1/History/PortCallRecordsByPort:
get:
summary: 3.6 Port Calls Records for Port
deprecated: false
description: "## Description\n\nThis Port Calls Records for Port service retrieves all vessels that have called at a port within a specified time frame by the port’s 5-digit port code. Returned data includes vessel basic details, port call records at the target port, and the corresponding previous/next port of call records for each vessel.\n\n## Use Cases\n\n1. **Logistics Tracking** \n Query and analyze the number of calling vessels, their berth distribution and port call time windows at a port during a specified period. Filter and aggregate the average vessel waiting time and operating time by vessel category, and estimate vessel queuing time at the port as a reference for overall voyage timeline calculation.\n\n2. **Port Analytics**\n\n## Request Limits\n\nAn API key must be created before using this service. \nService calls are subject to quota restrictions according to your permission type.\nThis service queries port call records within the latest month by default. To view your current service access permissions or enable the query for port call records covering 6 months, 12 months or a longer period, please contact our support team: support@elaneglobal.com. \n\n## Endpoint\n\n| Endpoint | HTTP Method |\n|----------|-------------|\n| `https://api.elaneglobal.com/v1/History/PortCallRecordsByPort` | GET |\n\n## Example API Call\n\n[https://api.elaneglobal.com/v1/History/PortCallRecordsByPort?key=1F6D701272402D1E7D8D316CCE519123&port_code=CNSHG&start_time=1744467589&end_time=1744967589]\n\n**Note:** \nThe key 1F6D701272402D1E7D8D316CCE519123 is the official key of elaneglobal.com, bound to the domain api.elaneglobal.com. \nUsers are not authorized to use this key for data access—utilizing it will return a status code 14, indicating an error in the source domain.\nTo trial the service, please contact our support team: support@elaneglobal.com. "
tags:
- History Dataset
parameters:
- name: key
in: query
description: Your personal Shipfinderer API key to verify service permissions
required: true
example: 1F6D701272402D1E7D8D316CCE519123
schema:
type: string
- name: port_code
in: query
description: Standard 5-digit port code
required: true
example: CNSHG
schema:
type: string
- name: start_time
in: query
description: Start time of historical berthing records, represented as a Unix timestamp. Both start_time and end_time are mandatory, defining the closed query interval [start_time, end_time]. A single query is limited to a maximum of 1 year (366 days) of port call records.
required: true
example: 1744467589
schema:
type: integer
- name: end_time
in: query
description: End time of historical berthing records, represented as a Unix timestamp.
required: true
example: 1744967589
schema:
type: integer
- name: type
in: query
description: 'Optional query type:
1=Query by ATA (Actual Time of Arrival);
2=Query by ATD (Actual Time of Departure).
Default: 1'
required: false
schema:
type: integer
- name: time_zone
in: query
description: 'Time zone type (optional): 1=Local time zone (UTC if unavailable); 2=UTC+8; 3=UTC (Greenwich Mean Time). Default value: 2'
required: false
schema:
type: integer
responses:
'200':
description: Success. HTTP 200 with a JSON envelope whose "status" field is 0.
content:
application/json:
schema:
type: object
properties:
status:
type: integer
msg:
type: string
total:
type: integer
data:
type: array
items:
type: object
properties:
imo:
type: integer
description: 7-digit numeric code of IMO
mmsi:
type: integer
description: 9-digit numeric code of MMSI
ship_type:
type: integer
description: 'Type of vessels: see Appendix for details. '
ship_name:
type: string
description: Vessel name
call_sign:
type: string
description: 'Call Sign '
currentport:
type: object
properties:
port_code:
type: string
description: Standard 5-digit port code
port_cnname:
type: string
description: Chinese name of the port
port_name:
type: string
description: Name of the port
port_time_zone:
type: string
description: Time zone of the port’s location
terminal_name:
type: string
description: Name of the terminal where the vessel berthed.
berth_name:
type: string
description: Name of the specific berth occupied by the vessel.
arrival_anchorage:
type: integer
description: Actual time of arrival at the anchorage. Time zone varies based on the time_zone parameter.
ata:
type: integer
description: Actual time of arrival at the port. Time zone varies based on the time_zone parameter.
atb:
type: integer
description: Actual time of berthing at the terminal. Time zone varies based on the time_zone parameter.
atd:
type: integer
description: Actual time of departure from the port. Time zone varies based on the time_zone parameter.
arrival_draught:
type: number
description: Vessel draft upon arrival at the port, in meters.
departure_draught:
type: number
description: Vessel draft upon departure from the port, in meters.
stay_time:
type: number
description: 'Total time the vessel stayed at the port, in hours. Calculated as: ATD − ATA'
stay_terminal_time:
type: number
description: 'Total time the vessel stayed at the terminal, in hours. Calculated as: ATD − ATB'
required:
- port_code
- port_cnname
- port_name
- port_time_zone
- terminal_name
- berth_name
- arrival_anchorage
- ata
- atb
- arrival_draught
- departure_draught
- stay_time
- stay_terminal_time
x-apifox-orders:
- port_code
- port_cnname
- port_name
- port_time_zone
- terminal_name
- berth_name
- arrival_anchorage
- ata
- atb
- atd
- arrival_draught
- departure_draught
- stay_time
- stay_terminal_time
description: 'List of current port of call information for the vessel. '
previousport:
type: object
properties:
port_code:
type: string
description: Standard 5-digit port code
port_cnname:
type: string
description: Chinese name of the port
port_name:
type: string
description: Name of the port
port_time_zone:
type: string
description: Time zone of the port’s location
arrival_anchorage:
type: integer
description: Actual time of arrival at the anchorage. Time zone varies based on the time_zone parameter.
ata:
type: integer
description: Actual time of arrival at the port. Time zone varies based on the time_zone parameter.
atb:
type: integer
description: Actual time of berthing at the terminal. Time zone varies based on the time_zone parameter.
atd:
type: integer
description: Actual time of departure from the port. Time zone varies based on the time_zone parameter.
required:
- port_code
- port_cnname
- port_name
- port_time_zone
- arrival_anchorage
- ata
- atb
- atd
x-apifox-orders:
- port_code
- port_cnname
- port_name
- port_time_zone
- arrival_anchorage
- ata
- atb
- atd
description: List of the vessel’s previous port of call information.
nextport:
type: object
properties:
port_code:
type: string
description: Standard 5-digit port code
port_cnname:
type: string
description: Chinese name of the port
port_name:
type: string
description: Name of the port
port_time_zone:
type: string
description: Time zone of the port’s location
arrival_anchorage:
type: integer
description: Actual time of arrival at the anchorage. Time zone varies based on the time_zone parameter.
ata:
type: integer
description: Actual time of arrival at the port. Time zone varies based on the time_zone parameter.
atb:
type: integer
description: Actual time of berthing at the terminal. Time zone varies based on the time_zone parameter.
atd:
type: integer
description: Actual time of departure from the port. Time zone varies based on the time_zone parameter.
required:
- port_code
- port_cnname
- port_name
- port_time_zone
x-apifox-orders:
- port_code
- port_cnname
- port_name
- port_time_zone
- arrival_anchorage
- ata
- atb
- atd
description: Port of call information for the vessel’s next port. Returns empty if the vessel has not arrived at the next port.
required:
- imo
- mmsi
- ship_type
- ship_name
- call_sign
- currentport
- previousport
- nextport
x-apifox-orders:
- imo
- mmsi
- ship_type
- ship_name
- call_sign
- currentport
- previousport
- nextport
required:
- status
- msg
- total
- data
x-apifox-orders:
- status
- msg
- total
- data
example: "{\n \"status\": 0,\n \"msg\": \"\",\n \"total\": 5140,\n \"data\": [\n {\n \"imo\": 0,\n \"mmsi\": 413842124,\n \"ship_type\": \"70\",\n \"ship_name\": \"ZHEJIAXINGHUO03191\",\n \"call_sign\": \"0\",\n \"currentport\": {\n \"port_code\": \"27999\",\n \"port_cnname\": \"上海\",\n \"port_name\": \"Shanghai\",\n \"port_time_zone\": \"+8\",\n \"terminal_name\": \"\",\n \"berth_name\": \"\",\n \"arrival_anchorage\": ,\n \"ata\": 1744468393,\n \"atb\": 1744468393,\n \"atd\": 1744635846,\n \"arrival_draught\": 0,\n \"departure_draught\": 0,\n \"stay_time\": 46.51,\n \"stay_terminal_time\": 46.51\n },\n \"previousport\": {\n \"port_code\": \"27999\",\n \"port_cnname\": \"上海\",\n \"port_name\": \"Shanghai\",\n \"port_time_zone\": \"+8\",\n \"arrival_anchorage\": \"\",\n \"ata\": 1744110014,\n \"atb\": 1744110014,\n \"atd\": 1744120857\n },\n \"nextport\": {\n \"port_code\": \"213479\",\n \"port_cnname\": \"奉贤\",\n \"port_name\": \"Fengxian\",\n \"port_time_zone\": \"+8\",\n \"arrival_anchorage\": \"\",\n \"ata\": 1744484085,\n \"atb\": 1744484085,\n \"atd\": 1744498411\n }\n },\n {\n \"imo\": 9302530,\n \"mmsi\": 412046070,\n \"ship_type\": \"90\",\n \"ship_name\": \"HU JIU 18\",\n \"call_sign\": \"BSAR\",\n \"currentport\": {\n \"port_code\": \"27999\",\n \"port_cnname\": \"上海\",\n \"port_name\": \"Shanghai\",\n \"port_time_zone\": \"+8\",\n \"terminal_name\": \"Eastern Tankstore Shanghai\",\n \"berth_name\": \"No 2\",\n \"arrival_anchorage\": \"\",\n \"ata\": 1744469305,\n \"atb\": 1744469305,\n \"atd\": 1745489204,\n \"arrival_draught\": 3500,\n \"departure_draught\": 3500,\n \"stay_time\": 283.31,\n \"stay_terminal_time\": 283.31\n },\n \"previousport\": {\n \"port_code\": \"213784\",\n \"port_cnname\": \"崇明\",\n \"port_name\": \"Chongming\",\n \"port_time_zone\": \"+8\",\n \"arrival_anchorage\": \"\",\n \"ata\": 1744469305,\n \"atb\": 1744469305,\n \"atd\": 1745489204\n },\n \"nextport\": {\n \"port_code\": \"213784\",\n \"port_cnname\": \"崇明\",\n \"port_name\": \"Chongming\",\n \"port_time_zone\": \"+8\",\n \"arrival_anchorage\": \"\",\n \"ata\": 1744469305,\n \"atb\": 1744469305,\n \"atd\": 1745489204\n }\n },\n ......\n ]\n}"
headers: {}
x-apifox-name: success
security:
- apiKeyQuery: []
x-apifox-folder: 3 History Dataset
x-apifox-status: released
x-run-in-apifox: https://app.apifox.com/web/project/7948067/apis/api-430531632-run
operationId: getPortCallRecordsByPort
externalDocs:
description: 3.6 Port Calls Records for Port
url: https://docs.shipfinder.com/430531632e0
/v1/History/PortCallRecordsByVessel:
get:
summary: 3.3 Vessel Port Call History
deprecated: false
description: "## Description\nThe Vessel Port Call History queries a vessel’s historical port call records within a specified time period. It returns the vessel’s anchorage arrival time, port limits arrival time, berthing time, port dwell time, inbound and outbound draft conditions, and other relevant details.\n\n## Use Cases\n1. **Maritime Supervision** \n Analyze whether foreign vessels have berthed at high-risk ports based on historical berthing records, and verify the authenticity and accuracy of entry declaration information.\n\n2. **Logistics Tracking** \n Track vessel voyage information, settle freight and trace logistics records based on actual port call times and voyage durations, and verify cargo loading/unloading activities by changes in vessel draft.\n\n3. **Financial & Insurance** \n Compare and verify port call records and draft change records for each vessel voyage against shipping order data, to conduct vessel risk assessment and analysis.\n\n## Request Limits\nAn API key must be created before using this service. \nService calls are subject to quota restrictions according to your permission type.\nThis service queries port call records within the latest month by default. To view your current service access permissions or enable the query for port call records covering 6 months, 12 months or a longer period, please contact our support team: support@elaneglobal.com. \n\n## Endpoint\n| Endpoint | HTTP Method |\n| --- | --- |\n| `https://api.elaneglobal.com/v1/History/PortCallRecordsByVessel` | GET |\n\n## Example API Call\nhttps://api.elaneglobal.com/v1/History/PortCallRecordsByVessel?key=1F6D701272402D1E7D8D316CCE519123&mmsi=477172700&start_time=1744967589&end_time=1745572389\n\n**Note:** \nThe key 1F6D701272402D1E7D8D316CCE519123 is the official key of elaneglobal.com, bound to the domain api.elaneglobal.com. \nUsers are not authorized to use this key for data access—utilizing it will return a status code 14, indicating an error in the source domain.\nTo trial the service, please contact our support team: support@elaneglobal.com. "
tags:
- History Dataset
parameters:
- name: key
in: query
description: Your personal Shipfinderer API key to verify service permissions
required: true
example: 1F6D701272402D1E7D8D316CCE519123
schema:
type: string
- name: mmsi
in: query
description: '9-digit numeric code of MMSI
'
required: true
example: 477172700
schema:
type: integer
- name: imo
in: query
description: 7-digit numeric code of IMO
required: false
schema:
type: integer
- name: ship_name
in: query
description: "Vessel name. \nNote: Port call records for all distinct vessels sharing the same name will be returned if duplicate vessel names exist."
required: false
schema:
type: string
- name: call_sign
in: query
description: 'Call Sign.
Matching Rule: Spaces are optional; letters are case-insensitive. The sequence and quantity of letters and digits must be consistent with the queried call sign.
Note: Port call records for all distinct vessels with an identical call sign will be returned if duplicate call signs exist.'
required: false
schema:
type: string
- name: start_time
in: query
description: 'Start time of historical berthing records, represented as a Unix timestamp.
Both start_time and end_time are mandatory, defining the closed query interval [start_time, end_time]. A single query is limited to a maximum of 1 year (366 days) of port call records.'
required: true
example: 1744967589
schema:
type: integer
- name: end_time
in: query
description: End time of historical berthing records, represented as a Unix timestamp.
required: true
example: 1745572389
schema:
type: integer
- name: time_zone
in: query
description: 'Time zone type (optional):
1=Local time zone (UTC if unavailable);
2=UTC+8;
3=UTC (Greenwich Mean Time).
Default value: 2'
required: false
schema:
type: integer
responses:
'200':
description: Success. HTTP 200 with a JSON envelope whose "status" field is 0.
content:
application/json:
schema:
type: object
properties:
status:
type: integer
msg:
type: string
data:
type: array
items:
type: object
properties:
ship_name:
type: string
description: Vessel name
call_sign:
type: string
description: 'Call Sign '
imo:
type: integer
description: 7-digit numeric code of IMO
mmsi:
type: integer
description: 9-digit numeric code of MMSI
ship_type:
type: integer
description: 'Numeric code of vessel type: see Appendix for details '
port_cnname:
type: string
description: Chinese name of the port
port_name:
type: string
description: Name of the port
port_time_zone:
type: string
description: Time zone of the port’s location
port_code:
type: string
description: Standard five-digit port code
terminal_name:
type: string
description: Name of the terminal where the vessel berthed.
berth_name:
type: string
description: Name of the specific berth occupied by the vessel.
port_country_cnname:
type: string
description: Chinese name of the country/region where the port is located
port_country_name:
type: string
description: Name of the country/region where the port is located
port_country_code:
type: string
description: Standard code of the country/region where the port is located
arrval_anchorage:
type: string
description: Actual time of arrival at the anchorage. Time zone varies based on the time_zone parameter.
ata:
type: integer
description: Actual time of arrival at the port. Time zone varies based on the time_zone parameter.
atb:
type: integer
description: Actual time of berthing at the terminal. Time zone varies based on the time_zone parameter.
atd:
type: integer
description: Actual time of departure from the port. Time zone varies based on the time_zone parameter.
arrival_draught:
type: number
description: Vessel draft upon arrival at the port, in meters.
departure_draught:
type: number
description: Vessel draft upon departure from the port, in meters.
stay_time:
type: number
description: 'Total time the vessel stayed at the port, in hours. Calculated as: ATD − ATA'
stay_interminal_time:
type: number
description: 'Total time the vessel stayed at the terminal, in hours. Calculated as: ATD − ATB'
x-apifox-orders:
- ship_name
- call_sign
- imo
- mmsi
- ship_type
- port_cnname
- port_name
- port_time_zone
- port_code
- terminal_name
- berth_name
- port_country_cnname
- port_country_name
- port_country_code
- arrval_anchorage
- ata
- atb
- atd
- arrival_draught
- departure_draught
- stay_time
- stay_interminal_time
required:
- ship_name
- mmsi
- ship_type
- port_name
- port_time_zone
- port_code
- terminal_name
- berth_name
- port_country_cnname
- port_country_name
- port_country_code
- arrval_anchorage
- ata
- atb
- atd
- arrival_draught
- departure_draught
- stay_time
- stay_interminal_time
required:
- status
- msg
- data
x-apifox-orders:
- status
- msg
- data
example: "{\n \"status\": 0,\n \"msg\": \"\",\n \"data\": [\n {\n \"ship_name\": \"COSCOSHIPPINGLIBRA\",\n \"call_sign\": \"VRRV4\",\n \"imo\": 9783538,\n \"mmsi\": 477172700,\n \"ship_type\": 71,\n \"port_cnname\": \"广州\",\n \"port_name\": \"Guangzhou\",\n \"port_time_zone\": \"+8\",\n \"port_code\": \"CNGZG\",\n \"terminal_name\": \"\",\n \"berth_name\": \"\",\n \"port_country_cnname\": \"中国\",\n \"port_country_name\": \"China\",\n \"port_country_code\": \"CN\",\n \"arrval_anchorage\": ,\n \"ata\": 1745058319,\n \"atb\": 1745058319,\n \"atd\": 1745120468,\n \"arrival_draught\": 13.5,\n \"departure_draught\": 14.5,\n \"stay_time\": 17.26,\n \"stay_interminal_time\": 17.26\n }\n ]\n}"
headers: {}
x-apifox-name: success
security:
- apiKeyQuery: []
x-apifox-folder: 3 History Dataset
x-apifox-status: released
x-run-in-apifox: https://app.apifox.com/web/project/7948067/apis/api-430426234-run
operationId: getPortCallRecordsByVessel
externalDocs:
description: 3.3 Vessel Port Call History
url: https://docs.shipfinder.com/430426234e0
/v1/History/PortCallRecordsByVesselAtPort:
get:
summary: 3.4 Vessel Port Call Records at Specific Port
deprecated: false
description: "## Description\nThe Vessel Port Call Records queries a vessel’s port call records at a specific designated port within a specified time period. It returns the vessel’s time of arrival at the anchorage, time of arrival within port limits, time of berthing at the berth, port stay duration, as well as the vessel’s draft conditions upon port entry and departure.\n\n## Use Cases\n1. **Maritime Supervision** \n Analyze whether foreign vessels have berthed at high-risk ports based on historical port call records, and verify the authenticity and accuracy of the relevant entry declaration information.\n\n2. **Logistics Tracking** \n Track vessel voyage details, settle freight and trace logistics records based on actual port entry/departure times and voyage durations, and verify cargo loading/unloading operations through changes in vessel draft.\n\n3. **Finance & Insurance** \n Cross-verify port call records and draft fluctuation records of each vessel voyage against shipping order data for vessel risk analysis and authenticity validation.\n\n## Request Limits\nAn API key must be created before using this service. \nService calls are subject to quota restrictions according to your permission type.\nThis service queries port call records within the latest month by default. To view your current service access permissions or enable the query for port call records covering 6 months, 12 months or a longer period, please contact our support team: support@elaneglobal.com. \n\n## Endpoint\n| Endpoint | HTTP Method |\n|----------|-------------|\n| `https://api.elaneglobal.com/v1/History/PortCallRecordsByVesselAtPort` | Get |\n\n## Example API Call\nhttps://api.elaneglobal.com/v1/History/PortCallRecordsByVesselAtPort?key=1F6D701272402D1E7D8D316CCE519123&mmsi=477172700&port_code=CNGZG&start_time=1744967589
# --- truncated at 32 KB (75 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/shipfinder-ais-data-api/refs/heads/main/openapi/shipfinder-ais-data-api-history-dataset-api-openapi.yml