Shipfinder, via Shipfinder API(Application Programming Interface), embeds ships position and map in user's business system or website simply and easily, helps users to create vessel management and monitoring system
Ship Data Ship Track Portofcall Data Single Ship Locate
Ship SearchSingle ShipMultiple ShipsArea ShipsAround Ships
Ship Search Interface, is an interface for users to get Shipfinder unique ShipID of any ship. Users can get ShipID with “Ship Name”, “Call Sign”, “IMO number”, “MMSI”
Parameter name | Description |
---|---|
v | Version Number:Version number is 2 |
k | API Key :API key provided by Shipfinder (Authorization Key) |
enc | Feedback Type :0 - Binary Base64 encoding, 1 - Json. Default Value: 1 |
kw | Key Word:Ship parameter, Ship Name/Call Sign/MMSI/IMO workable |
max | Max feedback of the request, should be not more than 100 |
jsf | Name of the function to be added outside the feedback result. |
https://jpapi.shipfinder.com/apicall/QueryShip?v=2&k=userkey&enc=1&kw=cosco&max=3
▪ JSON Response
♢ Sample
♢ Response Fields
Parameter name | Type | Description |
---|---|---|
MatchType | byte | Matching type: 1-Ship Name; 2-Call Sign;3-MMSI; 5-IMO |
ShipID | uint64 | Ship ID |
From | uint32 | Source of the data:
0-Coastal AIS receiver;1-Statellite AIS receiver |
mmsi | uint32 | MMSI |
shiptype | uint16 | As per ship type code in API Documentation |
imo | uint32 | 0= Not available (default) 2147483647=Null |
name | string | Ship Name |
callsign | string | Call Sign |
lasttime | int64 | Unix timestamp |
▪ Binary response
Parameter name | Type | Description |
---|---|---|
dataLength | uint32 | Length of the data |
dataType | uint16 | Type of the data :Definition as per in API Documentation |
resultcount | uint32 | Count of result |
matchType | byte | Match type :1-Ship Name;2-Call Sig;3-MMSI;5-IMO number |
User can get ship position data via Single Ship Query, using ShipID(MMSI) they get in ‘Ship Search’
Parameter name | Description |
---|---|
v | Version Number:Version number is 2 |
k | API Key :API key provided by Shipfinder (Authorization Key) |
enc | Feedback Type :0 - Binary Base64 encoding, 1 - Json. Default setting: 1 |
Id | ShipID :Unique ID for each ship on Shipfinder |
Idtype | ID type :0 - mmsi as ShipID, 1 – IMO as ShipID. Default setting: 0 |
jsf | Name of the function to be added outside the feedback result. |
https://jpapi.shipfinder.com/apicall/GetSingleShip?v=2&k=userkey&enc=1&id=477765900&idtype=0
▪ JSON Response
♢ Sample
♢ Response Fields
Parameter name | Type | Description |
---|---|---|
ShipID | uint64 | Ship ID |
From | uint32 | Source of the data:
0-Coastal AIS receiver;1-Statellite AIS receiver |
mmsi | uint32 | MMSI number of the ship, 9 digits |
shiptype | uint16 | As per ship type code in API Documentation |
imo | uint32 | 0= Not available (default) 2147483647=Null |
name | string | Ship Name |
callsign | string | Call Sign |
length | uint16 | Ship length, decimeter (0-10220) |
width | uint16 | Ship beam, decimeter (0-1260] |
left | uint16 | Distance to portside, decimeter(0-630] |
trail | uint16 | Distance to stern, decimeter(0-5110) |
draught | uint16 | Draft, millimeter(0-25500] |
dest | string | Destination |
dest_std | string | Standardized Destination |
destcode | string | Port code of the Standardized Destination |
eta | byte[4] | [MM][DD][HH][MM] |
eta_std | byte[4] | Standardized ETA:[YYYY] [MM][DD][HH][MM] |
navistat | uint16 | Navigation status, status detail as per in API Documentation |
lon | int32 | Longitude,
1/1000000 degree, [-180000000,18000000] |
lat | int32 | Latitude
1/1000000 degree, [-90000000,90000000] |
hdg | uint16 | Heading, 1/100 degree, [0,35900] |
cog | uint16 | Course, 1/100 degree, [0,35990] |
sog | uint16 | Speed, millimeter/second, [0,52576] |
rot | uint16 | Rate of turn, 1/100 degree/second,
[-1200,1200] |
lasttime | int64 | Unix timestamp |
▪ Binary response
Parameter name | Type | Description |
---|---|---|
dataLength | uint32 | Length of the data |
dataType | uint16> | Type of the data :Definition as per in API Documentation |
stShipDetai | stShipDetai | Ship information |
User can get ship data of several ships via Multiple Ship Query. Considering performance of the system, Multiple Ships Query will return ship data of max 100 ships once.
Parameter name | Description |
---|---|
v | Version Number :Version number is 2 |
k | API Key :API key provided by Shipfinder (Authorization Key) |
enc | Feedback Type :0 - Binary Base64 encoding, 1 - Json. Default setting: 1 |
Id | ShipID :Unique ID(MMSI) for each ship on Shipfinder |
jsf | Name of the function to be added outside the feedback result. |
https://jpapi.shipfinder.com/apicall/GetManyShip?v=2&k=userkey&enc=1&id=477765900,413503330
▪ JSON Response
♢ Sample
♢ Response Fields
Parameter name | Type | Description |
---|---|---|
ShipID | uint64 | Ship ID |
From | uint32 | Source of the data:
0-Coastal AIS receiver;1-Statellite AIS receiver |
mmsi | uint32 | MMSI number of the ship, 9 digits |
shiptype | uint16 | As per ship type code in API Documentation |
imo | uint32 | 0= Not available (default) 2147483647=Null |
name | string | Ship Name |
callsign | string | Call Sign |
length | uint16 | Ship length, decimeter (0-10220) |
width | uint16 | Ship beam, decimeter (0-1260] |
left | uint16 | Distance to portside, decimeter(0-630] |
trail | uint16 | Distance to stern, decimeter(0-5110) |
draught | uint16 | Draft, millimeter(0-25500] |
dest | string | Destination |
dest_std | string | Standardized Destination |
destcode | string | Port code of the Standardized Destination |
eta | byte[4] | [MM][DD][HH][MM] |
eta_std | byte[4] | Standardized ETA:[YYYY] [MM][DD][HH][MM] |
navistat | uint16 | Navigation status, status detail as per in API Documentation |
lon | int32 | Longitude,
1/1000000 degree, [-180000000,18000000] |
lat | int32 | Latitude
1/1000000 degree, [-90000000,90000000] |
hdg | uint16 | Heading, 1/100 degree, [0,35900] |
cog | uint16 | Course, 1/100 degree, [0,35990] |
sog | uint16 | Speed, millimeter/second, [0,52576] |
rot | uint16 | Rate of turn, 1/100 degree/second,
[-1200,1200] |
lasttime | int64 | Unix timestamp |
▪ Binary response
Parameter name | Type | Description |
---|---|---|
dataLength | uint32 | Length of the data |
dataType | uint16 | Type of the data :Definition as per in API Documentation |
ShipCount | uint32 | Count of ship :maybe less than setted counts |
shipDetail | stShipDetai | Ship information :don’t return the ship not queried |
Users can get ship data of all ships in a certain area via Area Ship Query.
Parameter name | Description |
---|---|
v | Version Number :Version number is 2 |
k | API Key :API key provided by Shipfinder (Authorization Key) |
enc | Feedback Type :0 - Binary Base64 encoding, 1 - Json. Default setting: 1 |
jsf | Name of the function to be added outside the feedback result |
scode | Session code :0 - first request. The following request, please use return session code. Such as: 1422842447 |
xy | Latitude and longitude:the position separate by “-“. For example: (121400000,31500000-121600000,31500000) Unit: lon*106,lat *106- lon*106,lat *106 |
https://jpapi.shipfinder.com/apicall/GetAreaShip?v=2&k=userkey&enc=1&jsf=func&scode=0&xy=122700000,37000000-123000000,37000000-123000000,36500000-122700000,36500000
▪ JSON Response
♢ Sample
♢ Response Fields
Parameter name | Type | Description |
---|---|---|
ShipID | uint64 | Ship ID |
From | uint32 | Source of the data:
0-Coastal AIS receiver;1-Statellite AIS receiver |
mmsi | uint32 | MMSI number of the ship, 9 digits |
shiptype | uint16 | As per ship type code in API Documentation |
imo | uint32 | 0= Not available (default) 2147483647=Null |
name | string | Ship Name |
callsign | string | Call Sign |
length | uint16 | Ship length, decimeter (0-10220) |
width | uint16 | Ship beam, decimeter (0-1260] |
left | uint16 | Distance to portside, decimeter(0-630] |
trail | uint16 | Distance to stern, decimeter(0-5110) |
draught | uint16 | Draft, millimeter(0-25500] |
dest | string | Destination |
dest_std | string | Standardized Destination |
destcode | string | Port code of the Standardized Destination |
eta | byte[4] | [MM][DD][HH][MM] |
eta_std | byte[4] | Standardized ETA:[YYYY] [MM][DD][HH][MM] |
navistat | uint16 | Navigation status, status detail as per in API Documentation |
lon | int32 | Longitude,
1/1000000 degree, [-180000000,18000000] |
lat | int32 | Latitude
1/1000000 degree, [-90000000,90000000] |
hdg | uint16 | Heading, 1/100 degree, [0,35900] |
cog | uint16 | Course, 1/100 degree, [0,35990] |
sog | uint16 | Speed, millimeter/second, [0,52576] |
rot | uint16 | Rate of turn, 1/100 degree/second,
[-1200,1200] |
lasttime | int64 | Unix timestamp |
▪ Binary response
Parameter name | Type | Description |
---|---|---|
dataLength | uint32 | Length of the data |
dataType | uint16 | Definition as per in API Documentation |
serviceTime | int64 | Time of the server |
scode | uint32 | Shipfinder will generate session code, users need to use it to update data |
ShipCount | uint32 | Number of ships in feedback file |
shipDetail | stShipDetai | Extended ship information |
Users can query the ship data near a ship through the surrounding ships.
Parameter name | Description |
---|---|
v | Version Number :Version number is 2 |
k | API Key :API key provided by Shipfinder (Authorization Key) |
enc | Feedback Type :0 - Binary Base64 encoding, 1 - Json. Default setting: 1 |
jsf | Name of the function to be added outside the feedback result |
mode | Update mode: 0- all data; 1-updated part. |
scode | Session code :0 - first request. The following request, please use return session code. Such as: 1422842447 |
xy | Latitude and longitude:the position separate by “-“. For example: (121400000,31500000-121600000,31500000) Unit: lon*106,lat *106- lon*106,lat *106 |
https://jpapi.shipfinder.com/apicall/GetAroundShip?v=2&k=userkey&enc=1&jsf=func&mmsi=411041796&radius=10
▪ JSON Response
♢ Sample
♢ Response Fields
Parameter name | Type | Description |
---|---|---|
ShipID | uint64 | Ship ID |
From | uint32 | Source of the data:
0-Coastal AIS receiver;1-Statellite AIS receiver |
mmsi | uint32 | MMSI number of the ship, 9 digits |
shiptype | uint16 | As per ship type code in API Documentation |
imo | uint32 | 0= Not available (default) 2147483647=Null |
name | string | Ship Name |
callsign | string | Call Sign |
length | uint16 | Ship length, decimeter (0-10220) |
width | uint16 | Ship beam, decimeter (0-1260] |
left | uint16 | Distance to portside, decimeter(0-630] |
trail | uint16 | Distance to stern, decimeter(0-5110) |
draught | uint16 | Draft, millimeter(0-25500] |
dest | string | Destination |
dest_std | string | Standardized Destination |
destcode | string | Port code of the Standardized Destination |
eta | byte[4] | [MM][DD][HH][MM] |
eta_std | byte[4] | Standardized ETA:[YYYY] [MM][DD][HH][MM] |
navistat | uint16 | Navigation status, status detail as per in API Documentation |
lon | int32 | Longitude,
1/1000000 degree, [-180000000,18000000] |
lat | int32 | Latitude
1/1000000 degree, [-90000000,90000000] |
hdg | uint16 | Heading, 1/100 degree, [0,35900] |
cog | uint16 | Course, 1/100 degree, [0,35990] |
sog | uint16 | Speed, millimeter/second, [0,52576] |
rot | uint16 | Rate of turn, 1/100 degree/second,
[-1200,1200] |
lasttime | int64 | Unix timestamp |
▪ Binary response
Parameter name | Type | Description |
---|---|---|
dataLength | uint32 | Length of the data |
dataType | uint16 | Definition as per in API Documentation |
serviceTime | int64 | Time of the server |
scode | uint32 | Shipfinder will generate session code, users need to use it to update data |
ShipCount | uint32 | Number of ships in feedback file |
shipDetail | stShipDetai | Extended ship information |
Request for ship track data via ShipID (only MMSI number of the ship workable here)
Parameter name | Description |
---|---|
v | Version Number:Version number is 2 |
k | API Key :API key provided by Shipfinder (Authorization Key) |
enc | Feedback Type :0 - Binary Base64 encoding, 1 - Json. Default setting: 1 |
Id | ShipID :Unique ID for each ship on Shipfinder (mmsi) |
btm | Begin time of the track |
etm | End time of the track |
Jsf | Jason function :Jsf=f |
cut | Data Type :When ship data is very large, Shipfinder would cut track into pieces, and return separately. 0= no cut; 1=cut |
https://jpapi.shipfinder.com/apicall/GetShipTrack?v=2&k=userkey&enc=0&cut=1&id=412473010&btm=1393516800&etm=1394165100&jsf=f
▪ JSON Response
♢ Sample
♢ Response Fields
Parameter name | Type | Description |
---|---|---|
notall | int32 | 0:return all,1:teturn part |
points | int32 | Count of points |
datatype | uint32 | Source of the data:0:Coastal AIS receiver;1:Statellite AIS receiver |
utc | int64 | lastTime :Unix timestamp |
lon | int32 | Longitude
1/1000000 degree, [-180000000,18000000] |
lat | int32 | Latitude
1/1000000 degree, [-90000000,9000000] |
sog | uint16 | Speed, millimeter/second, [0,52576] |
cog | uint16 | Course, 1/100 degree, [0,35990] |
▪ Binary response
Parameter name | Type | Description |
---|---|---|
dataLength | uint32 | Length of the data |
dataType | uint16 | Type of the data :As per definition in API Documentation |
count | uint32 | Data packet counts |
lastTime | int64 | Unix timestamp |
from | uint16 | Data source |
lon | int32 | Longitude :1/1000000 degree, [-180000000,18000000] |
lat | int32 | Latitude :1/1000000 degree, [-90000000,9000000] |
sog | int16 | Speed over ground :Millimeter/second, [0,52576] |
cog | int16 | Course over ground :1/1000000 degree, [0-36000] |
continue | uint16 | 1=continue , 0=end |
Single Ship Portofcall Single Port Portofcall Ship Plus Port Portofcall
User can request for ship port of calling history by Ship Name / Call Sign / MMSI number / IMO number
Parameter name | Description |
---|---|
v | Version Number :Version number is 2 |
k | API Key :API key provided by Shipfinder (Authorization Key) |
mmsi | MMSI number of the ship |
imo | IMO number of the ship |
shipname | Name of the ship Matching principle: all space to be deleted, case-insensitive. ith the same name will be returned. |
callsign | Call Sign of the ship Matching principle: all space to be deleted, case-insensitive. All record of ships with the same call sign will be returned. |
begin | Start time of port of call record, unix timestamp; system will feedback records between[begin, end] Shipfinder API will return one year (366 days) port of call history once. |
end | End time of port of call record, unix timestamp |
timetype | 1. Local Time; 2. Beijing Time; 3. GMT time. Default Setting:2. |
jsf | Name of the function to be added outside the feedback result. |
▪ Request by MMSI of the ship:
https://jpapi.shipfinder.com/apicall/GetPortOfCallByShip?v=2&k=userkey&mmsi=412633000&begin=1450410918&end=1451447718&timetype=2
▪ Request by IMO of the Ship:
https://jpapi.shipfinder.com/apicall/GetPortOfCallByShip?v=2&k=userkey&imo=9437531&begin=1450410918&end=1451447718&timetype=2
▪ Request by Ship Name:
https://jpapi.shipfinder.com/apicall/GetPortOfCallByShip?v=2&k=userkey&shipname= TIAN JIN HE &begin=1450410918&end=1451447718&timetype=2
▪ Request by Call Sign of the ship:
https://jpapi.shipfinder.com/apicall/GetPortOfCallByShip?v=2&k=userkey&callsign=BOPG&begin=1450410918&end=1451447718&timetype=2
▪ JSON Response
♢ Sample
♢ Response Fields
Parameter name | Description |
---|---|
shipname | ship name |
callsign | ship call sign |
imo | ship IMO number |
mmsi | ship MMSI number, unique number of the ship |
shiptype_cn | ship type in Chinese |
shiptype_en | ship type in English |
portname_cn | port name in Chinese |
portname_en | port name in English |
portid | port id |
porttimezone | Time Zone of the Port |
portcode | port code, UNLCODE of the port |
terminalname | name of the terminal |
berthname | name of the Berth |
country_cn | Country name in Chinese |
country_en | Country name in English |
countrycode | Code of the country |
ata | actual time of arrive. Time Zone in the feedback is determined by timetype in the request |
atb | actual time of berthing. Time Zone in the feedback is determined by timetype in the request |
atd | actual time of departure. Time Zone in the feedback is determined by timetype in the request |
arrivaldraught | Draft of the ship at ATA |
departuredraught | Draft of the ship at ATD |
stayinport | time of the ship stays in port,hours,ATD-ATA |
stayinterminal | time of the ship stays in terminal,hours, ATD-ATB |
User can request for ship calling record of a port by portID / port code.
Parameter name | Description |
---|---|
v | Version Number :Version number is 2 |
k | API Key :API key provided by Shipfinder (Authorization Key) |
portid | Identification ID of the port in Shipfinder. As per in API Documentation |
portcode | Identification Code of the port in Shipfinder. As per in API Documentation |
begin | Start time of port of call record, unix timestamp system will feedback records between[begin, end], but maximum seven days. |
end | End time of port of call record, unix timestamp |
type | Query type. 1. ATA query; 2. ATD query; 3. ATA & ATD query. Default setting: 1. |
timetype | 1. Local Time; 2. Beijing Time; 3. GMT time. Default Setting:2. |
jsf | Name of the function to be added outside the feedback result. |
▪ Query request by PortID:
https://jpapi.shipfinder.com/apicall/GetPortOfCallByPort?v=2&k=userkey&portid=27400&begin=1450058400&end=1450101600&type=1&timetype=2
▪ Query request by Port Code:
https://jpapi.shipfinder.com/apicall/GetPortOfCallByPort?v=2&k=userkey&portcode=CNGZH&begin=1450058400&end=1450101600&type=1&timetype=2
▪ JSON Response
♢ Sample
♢ Response Fields
Parameter name | Description |
---|---|
shipname | ship name |
callsign | ship call sign |
imo | ship IMO number |
mmsi | ship MMSI number, unique number of the ship |
shiptype_cn | ship type in Chinese |
shiptype_en | ship type in English |
currentport | port information of current port of the ship |
portid | port id |
portname_cn | port name in Chinese |
portname_en | port name in English |
porttimezone | Time Zone of the Port |
terminalname | name of the terminal |
berthname | name of the Berth |
ata | actual time of arrive, time zone verifies as per “TimeType” setting |
atb | actual time of berthing, time zone verifies as per “TimeType” setting |
atd | actual time of departure, time zone verifies as per “TimeType” setting |
arrivaldraught | Draft of the ship at ATA |
departuredraught | Draft of the ship at ATD |
stayinport | time of the ship stays in port, hours,ATD-ATA |
stayinterminal | time of the ship stays in terminal, hours,ATD-ATB |
previousport | port information of last port of the ship |
nextport | port information of next port of the ship |
Users can request for calling records of a ship at several ports, by Ship Name / Call Sign / MMSI number / IMO number.
Parameter name | Description |
---|---|
v | Version Number :Version number is 2 |
k | API Key:API key provided by Shipfinder (Authorization Key) |
mmsi | MMSI number of the ship |
imo | IMO number of the ship |
shipname | Name of the ship Matching principle: all space to be deleted, case-insensitive. All record of ships with the same name will be returned. |
callsign | Call Sign of the ship Matching principle: all space to be deleted, case-insensitive. All record of ships with the same call sign will be returned. |
portid | ID of the port in Shipfinder, separate port with “,” |
begin | Start time of port of call record, unix timestamp System will feedback records between[begin, end] Shipfinder API will return one year (366 days) port of call history once |
end | End time of port of call record, unix timestamp |
timetype | 1. Local Time; 2. Beijing Time; 3. GMT time. Default Setting:2. |
jsf | Name of the function to be added outside the feedback result. |
▪ Request by MMSI of the ship:
https://jpapi.shipfinder.com/apicall/GetPortOfCallByShipPort?v=2&k=userkey&mmsi=412633000&portid=22214,12563&begin=1450410918&end=1451447718&timetype=2
▪ Request by IMO of the ship:
https://jpapi.shipfinder.com/apicall/GetPortOfCallByShipPort?v=2&k=userkey&imo= 9437531&portid=22214,12563&begin=1450410918&end=1451447718&timetype=2
▪ Request by Ship Name of the ship:
https://jpapi.shipfinder.com/apicall/GetPortOfCallByShipPort?v=2&k=userkey& shipname = TIAN JIN HE &portid=22214,12563&begin=1450410918&end=1451447718&timetype=2
▪ Request by Call Sign of the ship:
https://jpapi.shipfinder.com/apicall/GetPortOfCallByShipPort?v=2&k=userkey& callsign = BOPG 412633000&portid=22214,12563&begin=1450410918&end=1451447718&timetype=2
▪ JSON Response
♢ Sample
♢ Response Fields
Parameter name | Description |
---|---|
shipname | ship name |
callsign | ship call sign |
imo | ship IMO number |
mmsi | ship MMSI number, unique number of the ship |
shiptype_cn | ship type in Chinese |
shiptype_en | ship type in English |
portname_cn | port name in Chinese |
portname_en | port name in English |
portid | port id |
porttimezone | Time Zone of the Port |
portcode | port code, UNLCODE of the port |
terminalname | name of the terminal |
berthname | name of the Berth |
country_cn | Country name in Chinese |
country_en | Country name in English |
countrycode | Code of the country |
ata | actual time of arrive, time zone verifies as per “TimeType” setting |
atb | actual time of berthing, time zone verifies as per “TimeType” setting |
atd | actual time of departure, time zone verifies as per “TimeType” setting |
arrivaldraught | Draft of the ship at ATA |
departuredraught | Draft of the ship at ATD |
stayinport | time of the ship stays in port, hours,ATD-ATA |
stayinterminal | time of the ship stays in terminal, hours,ATD-ATB |
Users can display data of the ship on map after getting it via “Ship Name”, “Call Sign”, “IMO number”, “MMSI”.
Remarks: Developed based on HTML 5, can be used on Mobile platforms.
Parameter name | Description |
---|---|
k | API Key :API key provided by Shipfinder (Authorization Key) |
kw | Key Word:Ship parameter, Ship Name/Call Sign/MMSI/IMO workable |
tip | Info Box controller. 0: don’t show box; 1: Show box. Tip=1, use ship coordination as the center. Tip=0 & track=1, use center the track as the center. |
track | Track controller. 0: don’t show track, default setting; 1: show track, default setting (if trackstart and trackend is null): recent 7 days track. |
trackstart | Start time of the track, in Unix timestamp format. |
trackend | End time of the track, in Unix timestamp format. |
tabs | Add info tab: width: 300px; height:200px. Name: name of the tab; url: add info source website. Use comma(,) as separate for multiple tabs. Max 3 tabs supported. Format Example: [{'name':'','url':''},{'name':'','url':''}] |
https://jpapi.shipfinder.com/apicall/location?k=userkey&kw=xinweihai&tip=1&track=1&trackstart=1493013738&trackend=1493100138&tabs=[{'name':'','url':''}]
kw: | tip:hideshow track:hideshow |
trackstart: | trackend: |
tabs_name1: | tabs_url1: |
tabs_name2: | tabs_url2: |
tabs_name3: | tabs_url3: |