openapi: 3.2.0
info:
title: ShipFinder Global Maritime Data AIS 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: AIS Dataset
paths:
/v1/AIS/FleetPosition:
get:
summary: 1.1.3 Fleet Position
deprecated: false
description: ''
tags:
- AIS Dataset
parameters:
- name: key
in: query
description: fleet ID personal Shipfinder API key to verify service permissions
required: true
example: 1F6D701272402D1E7D8D316CCE519123
schema:
type: string
- name: fleet_id
in: query
description: 'All vessel positions under the fleet can be retrieved by the fleet ID maintained in the Dashboard. '
required: true
example: 98f1f00a-d2d4-431b-90bf-d5471b184ff6
schema:
type: string
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:
fleet_id:
type: string
description: Your fleet ID
mmsi:
type: integer
description: 9-digit numeric code of MMSI
imo:
type: integer
description: 7-digit numeric code of IMO
call_sign:
type: string
description: 'Call Sign '
ship_name:
type: string
description: Vessel name
ship_cnname:
type: string
description: Chinese name of the vessel
data_source:
type: string
description: 0=Terrestrial AIS stations or Shipborne AIS; 1=Satellite AIS
lat:
type: number
description: Coordinate latitude, WGS84 coordinate system
lng:
type: number
description: Coordinate longitude, WGS84 coordinate system
ship_type:
type: integer
length:
type: number
description: 'Vessel length in meters, valid value range: 0–1022'
width:
type: number
description: Vessel breadth in meters (nautical standard term)
left:
type: number
description: Port distance in meters
trail:
type: number
description: Stern Distance in meters
draught:
type: number
description: Vessel draught depth in meters
dest:
type: string
description: Standardized destination port names, e.g., SINGAPORE, SG
destcode:
type: string
description: Port code of the destination, e.g., SGSGP
navistat:
type: integer
description: 0, Vessel navigation status; -1=invalid data
sog:
type: number
description: Real-time vessel speed over ground in knots; -1=invalid data
cog:
type: number
description: Course over ground in degrees ; -1=invalid data
hdg:
type: integer
description: Vessel heading in degrees; 511=invalid data
rot:
type: number
description: Rate of turn in degrees per minute
last_time:
type: integer
description: AIS last update time in Unix timestamp
eta:
type: integer
description: Estimated Time of Arrival in Unix timestamp
required:
- fleet_id
- mmsi
- imo
- call_sign
- ship_name
- ship_cnname
- data_source
- last_time
- lat
- lng
- ship_type
- length
- width
- left
- trail
- draught
- dest
- destcode
- eta
- navistat
- sog
- cog
- hdg
- rot
x-apifox-orders:
- fleet_id
- mmsi
- imo
- call_sign
- ship_name
- ship_cnname
- data_source
- last_time
- lat
- lng
- ship_type
- length
- width
- left
- trail
- draught
- dest
- destcode
- eta
- navistat
- sog
- cog
- hdg
- rot
required:
- status
- msg
- total
- data
x-apifox-orders:
- status
- msg
- total
- data
example:
status: 0
msg: ''
total: 3
data:
- fleet_id: 98f1f00a-d2d4-431b-90bf-d5471b184ff6
mmsi: 241673000
imo: 9852119
call_sign: SVDF6
ship_name: SEA EMERALD
ship_cnname: ''
data_source: 1
last_time: 1774950228
lat: 25.622803
lng: 53.367208
ship_type: 80
length: 336
width: 60
left: 31
trail: 55
draught: 20.4
dest: CNZNG
destcode: ''
eta: 1776283200
navistat: 0
sog: 0.7003891
cog: 286.1
hdg: 126
rot: -0.01
- fleet_id: 98f1f00a-d2d4-431b-90bf-d5471b184ff6
mmsi: 477985700
imo: 9308479
call_sign: VRDJ3
ship_name: DAPENG SUN
ship_cnname: ''
data_source: 1
last_time: 1774950155
lat: 21.452173
lng: 114.80732
ship_type: 80
length: 291
width: 43
left: 22
trail: 55
draught: 9.6
dest: CN DPGAU DAM
destcode: ''
eta: 1775660400
navistat: 0
sog: 16.2140083
cog: 178.8
hdg: 179
rot: 0
headers: {}
x-apifox-name: success
security:
- apiKeyQuery: []
x-apifox-folder: 1 AIS Dataset/1.1 Vessel Position
x-apifox-status: released
x-run-in-apifox: https://app.apifox.com/web/project/7948067/apis/api-430293359-run
operationId: getFleetPosition
externalDocs:
description: 1.1.3 Fleet Position
url: https://docs.shipfinder.com/430293359e0
/v1/AIS/VesselFlagInfo:
get:
summary: 1.5 Vessel Flag Information
deprecated: false
description: "## Description\nThe Vessel Flag Information queries the flag state (country/region) information of the matching vessel by the vessel’s MMSI number.\n\n## Use Case\n### Maritime Supervision\nUsing the vessel MMSI numbers obtained from area-based vessel search results or port berthing vessel lists, this service quickly matches the country/region of registration for the target vessels. It supports analysis of the proportion and operational behaviors of foreign vessels within the port or specific designated maritime areas.\n\n## Request Limits\nAn API key must be created before using this service. API calls are subject to quota restrictions according to your permission type. To view your current service access permissions, please contact our support team: support@elaneglobal.com. \n\n## Endpoint\n| Endpoint | HTTP Method |\n|----------|-------------|\n| `https://api.elaneglobal.com/v1/AIS/VesselFlagInfo` | GET |\n\n## Example API Call\nhttps://api.elaneglobal.com/v1/AIS/VesselFlagInfo?key=1F6D701272402D1E7D8D316CCE519123&mmsi=477172700\n\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:
- AIS 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
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
description: API call status code,0 means success
msg:
type: string
description: Exception prompt message
data:
type: object
properties:
mmsi:
type: integer
description: 9-digit numeric code of MMSI
registry:
type: string
description: Name of the vessel’s flag state (country/region)
required:
- mmsi
- registry
x-apifox-orders:
- mmsi
- registry
required:
- status
- msg
- data
x-apifox-orders:
- status
- msg
- data
example:
status: 0
msg: ''
data:
mmsi: 477172700
registry: Panama
headers: {}
x-apifox-name: success
security:
- apiKeyQuery: []
x-apifox-folder: 1 AIS Dataset
x-apifox-status: released
x-run-in-apifox: https://app.apifox.com/web/project/7948067/apis/api-429919472-run
operationId: getVesselFlagInfo
externalDocs:
description: 1.5 Vessel Flag Information
url: https://docs.shipfinder.com/429919472e0
/v1/AIS/VesselPositionMulti:
get:
summary: 1.1.2 Multi-vessel Position
deprecated: false
description: '
'
tags:
- AIS Dataset
parameters:
- name: key
in: query
description: Your personal Shipfinderer API key to verify service permissions
required: true
example: 1F6D701272402D1E7D8D316CCE519123
schema:
type: string
- name: mmsis
in: query
description: For Multi-Vessel Search, 9-digit MMSIs shall be separated by English commas, with a maximum of 100 vessels per search. <br> **Note:** The required parameter is MMSIs (plural form), not the singular MMSI. For multi-vessel search, requests will still be processed successfully even if invalid parameter content is submitted. However, only valid 9-digit MMSIs will be counted toward your usage credits, and invalid MMSIs will not be recorded as used credits.
required: true
example: 477232800,477172700
schema:
type: string
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:
mmsi:
type: integer
description: 9-digit numeric code of MMSI
imo:
type: integer
description: 7-digit numeric code of IMO
call_sign:
type: string
description: 'Call Sign '
ship_name:
type: string
description: Vessel name
ship_cnname:
type: string
description: Chinese name of the vessel
data_source:
type: integer
description: 0=Terrestrial AIS stations or Shipborne AIS; 1=Satellite AIS
ship_type:
type: integer
description: 'Numeric code of vessel type: see Appendix for details '
length:
type: number
description: 'Vessel length in meters, valid value range: 0–1022'
width:
type: number
description: Vessel breadth in meters (nautical standard term)
left:
type: number
description: Port distance in meters
trail:
type: number
description: Stern Distance in meters
draught:
type: number
description: Vessel draught depth in meters
dest:
type: string
description: Standardized destination port names, e.g., SINGAPORE, SG
destcode:
type: string
description: Port code of the destination, e.g., SGSGP
navistat:
type: integer
description: 0, Vessel navigation status; -1=invalid data
lat:
type: number
description: Coordinate latitude, WGS84 coordinate system
lng:
type: number
description: Coordinate longitude, WGS84 coordinate system
sog:
type: number
description: Real-time vessel speed over ground in knots; -1=invalid data
cog:
type: number
description: Course over ground in degrees ; -1=invalid data
hdg:
type: number
description: Vessel heading in degrees; 511=invalid data
rot:
type: number
description: Rate of turn in degrees per minute
last_time:
type: integer
description: AIS last update time in Unix timestamp
eta:
type: integer
description: Estimated Time of Arrival in Unix timestamp
required:
- mmsi
- imo
- call_sign
- ship_name
- ship_cnname
- data_source
- ship_type
- length
- width
- left
- trail
- draught
- dest
- destcode
- eta
- navistat
- lat
- lng
- sog
- cog
- hdg
- rot
- last_time
x-apifox-orders:
- mmsi
- imo
- call_sign
- ship_name
- ship_cnname
- data_source
- ship_type
- length
- width
- left
- trail
- draught
- dest
- destcode
- eta
- navistat
- lat
- lng
- sog
- cog
- hdg
- rot
- last_time
required:
- status
- msg
- data
x-apifox-orders:
- status
- msg
- data
example:
status: 0
msg: ''
data:
- mmsi: 477232800
imo: 9789647
call_sign: VRSG2
ship_name: COSCO PISCES
ship_cnname: ''
data_source: 1
ship_type: 100
length: 400
width: 59
left: 24
trail: 241
draught: 12.5
dest: 'ESVLC > SGSIN-PWBGA '
destcode: ''
eta: 1775145600
navistat: 0
lat: 4.095627
lng: 92.529245
sog: 12.7
cog: 48.5
hdg: 49
rot: 0
last_time: 1774945102
- mmsi: 477172700
imo: 9783538
call_sign: VRRV4
ship_name: COSCO SHIPPING LIBRA
ship_cnname: ''
data_source: 1
ship_type: 100
length: 399
width: 59
left: 33
trail: 256
draught: 13
dest: SHANGHAI,CN
destcode: CNSHG
eta: 1776691800
navistat: 0
lat: -21.220912
lng: 6.866182
sog: 17.9
cog: 142.9
hdg: 143
rot: 0
last_time: 1774945234
headers: {}
x-apifox-name: success
security:
- apiKeyQuery: []
x-apifox-folder: 1 AIS Dataset/1.1 Vessel Position
x-apifox-status: released
x-run-in-apifox: https://app.apifox.com/web/project/7948067/apis/api-430292321-run
operationId: getVesselPositionMulti
externalDocs:
description: 1.1.2 Multi-vessel Position
url: https://docs.shipfinder.com/430292321e0
/v1/AIS/VesselPositionSingle:
get:
summary: 1.1.1 Single Vessel Position
deprecated: false
description: ''
tags:
- AIS Dataset
parameters:
- name: key
in: query
description: Your personal Shipfinder 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: '413149000'
schema:
type: string
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
description: API call status code,0 means success
msg:
type: string
description: Exception prompt message
data:
type: object
properties:
mmsi:
type: integer
description: 9-digit numeric code of MMSI
imo:
type: integer
description: 7-digit numeric code of IMO
call_sign:
type: string
description: 'Call Sign '
ship_name:
type: string
description: Vessel name
ship_cnname:
type: string
description: Chinese name of the vessel
data_source:
type: integer
description: 0=Terrestrial AIS stations or Shipborne AIS; 1=Satellite AIS
ship_type:
type: integer
description: 'Numeric code of vessel type: see Appendix for details '
length:
type: number
description: 'Vessel length in meters, valid value range: 0–1022'
width:
type: number
description: Vessel breadth in meters (nautical standard term)
left:
type: number
description: Port distance in meters
trail:
type: number
description: Stern Distance in meters
draught:
type: number
description: Vessel draught depth in meters
dest:
type: string
description: Standardized destination port names, e.g., SINGAPORE, SG
destcode:
type: string
description: Port code of the destination, e.g., SGSGP
eta:
type: string
description: 'Estimated Time of Arrival. Format: YYYY-MM-DD HH:MM:SS, UTC'
navistat:
type: integer
description: 0, Vessel navigation status; -1=invalid data
lat:
type: number
description: Coordinate latitude, WGS84 coordinate system
lng:
type: number
description: Coordinate longitude, WGS84 coordinate system
sog:
type: number
description: Real-time vessel speed over ground in knots; -1=invalid data
cog:
type: number
description: Course over ground in degrees ; -1=invalid data
hdg:
type: number
description: Vessel heading in degrees; 511=invalid data
rot:
type: number
description: Rate of turn in degrees per minute
last_time:
type: integer
description: AIS last update time in Unix timestamp
required:
- mmsi
- imo
- call_sign
- ship_name
- ship_cnname
- data_source
- ship_type
- length
- width
- left
- trail
- draught
- dest
- destcode
- eta
- navistat
- lat
- lng
- sog
- cog
- hdg
- rot
- last_time
x-apifox-orders:
- mmsi
- imo
- call_sign
- ship_name
- ship_cnname
- data_source
- ship_type
- length
- width
- left
- trail
- draught
- dest
- destcode
- eta
- navistat
- lat
- lng
- sog
- cog
- hdg
- rot
- last_time
required:
- status
- msg
- data
x-apifox-orders:
- status
- msg
- data
example:
status: 0
msg: ''
data:
mmsi: 413961925
imo: 0
call_sign: P
ship_name: WANHONGYUAN369
ship_cnname: 皖鸿远369
data_source: 0
ship_type: 70
length: 68
width: 13
left: 8
trail: 18
draught: 4.8
dest: TAIZHOU,CN
destcode: CNTZO
eta: 1745827548
navistat: 0
lat: 32.192517
lng: 119.628093
sog: 6.2
cog: 80.8
hdg: 511
rot: 0
last_time: 1745827548
headers: {}
x-apifox-name: success
security:
- apiKeyQuery: []
x-apifox-folder: 1 AIS Dataset/1.1 Vessel Position
x-apifox-status: released
x-run-in-apifox: https://app.apifox.com/web/project/7948067/apis/api-428990613-run
operationId: getVesselPositionSingle
externalDocs:
description: 1.1.1 Single Vessel Position
url: https://docs.shipfinder.com/428990613e0
/v1/AIS/VesselSearch:
get:
summary: 1.2 Vessel Search
deprecated: false
description: "## Description\nThe Vessel Search API performs partial matching searches against keywords (MMSI, IMO Number, Vessel Name, Call Sign, etc.) to retrieve eligible vessel static records. It returns all historical MMSI records linked to a specified IMO Number, or information of all vessels that have ever used the given vessel name in history.\n\n**Note:** \nMaritime Mobile Service Identity (MMSI) is a 9-digit numeric code used in maritime radio communication systems for unique identification of individual and group call stations. Unique to each vessel, an MMSI code may be changed upon vessel sale; its first three digits indicate the country or region of registration. \nIMO Number (International Maritime Organization Number) is a unique 7-digit identifier assigned to each vessel by the International Maritime Organization, used for global tracking and administration of vessel identity, technical specifications and safety records.\n\n## Use Cases\nThis service is generally integrated into systems or platforms. Returned MMSI numbers can act as input parameters for Single Vessel Position Query and Vessel Historical Track Query, to retrieve real-time vessel position, operational status and historical voyage track. \nIf you have a defined vessel MMSI list, you may skip this service and use Single Vessel Position API or Multi-Vessel Position API directly for fleet monitoring and management.\n\n## Request Limits\nAn API key must be created before using this service. This API has no access frequency limits—unlimited calls are allowed once access permission is granted. To apply for or inquire about your access permission, please contact our support team: support@elaneglobal.com. \n\n## Endpoint\n| Endpoint | HTTP Method | Remarks |\n| --- | --- | --- |\n| `https://api.elaneglobal.com/v1/AIS/VesselSearch` | GET | When using partial matching with vessel name or IMO number, multiple results will be returned. You can distinguish them by referring to the latest AIS report time. Vessels may have their MMSI changed during ownership transfers or certain leasing processes. Old MMSI numbers will still be retained in records—filter them based on your specific use case. |\n\n## Example API Call\nhttps://api.elaneglobal.com/apicall/v3/VesselSearch?key=1F6D701272402D1E7D8D316CCE519123&keywords=DENEBLEADER&max=5\nNote:\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
# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/shipfinder-ais-data-api/refs/heads/main/openapi/shipfinder-ais-data-api-ais-dataset-api-openapi.yml