SailNavSim API

SailNavSim

This page provides some documentation for the SailNavSim API, which can be used to obtain boat and race data in a machine-friendly format (JSON). This may be especially of use to anyone who would like to more easily perform analysis of their boat's data, or to create alternative interfaces for viewing the data and even controlling their boat.

Note that this API may be extended in the future without notice. Additional capabilities and values beyond those listed here may exist and are likely to continue to be added in the future. However, efforts will be made to avoid removing any existing capabilities and values and to otherwise maintain backwards compatibility going forward.

Boat Info

Description: Provides the most recent per-minute data from the boat log for the requested boat key.

Path: /sailnavsim/api/boatinfo.php
Supported methods: GET

URL request parameters:

key - the boat key for which to request data

Response body: A JSON-encoded object, which includes the following values:

Name	Type (units)	Description
time	Number (seconds)	Unix epoch time of this boat log report
lat	Number (degrees)	Boat position latitude in decimal degrees
lon	Number (degrees)	Boat position longitude in decimal degrees
courseWater	Number (degrees)	Boat course through water
speedWater	Number (metres/second)	Boat speed through water
trackGround	Number (degrees)	Boat track over ground
speedGround	Number (metres/second)	Boat speed over ground (SOG)
windDir	Number (degrees)	Compass direction from which the true wind is blowing
windSpeed	Number (metres/second)	Wind speed
windGust	Number (metres/second)	Wind gust speed
oceanCurrentDir	Number (degrees) or Null	Compass direction towards which the ocean surface current is flowing; may be null if ocean data is not available at boat position
oceanCurrentSpeed	Number (metres/second) or Null	Ocean surface current speed; may be null if ocean data is not available at boat position
oceanIce	Number (percent) or Null	Sea ice concentration; may be null if ocean data is not available at boat position
distanceTravelled	Number (metres)	Total distance the boat has travelled
damage	Number (percent)	Boat damage amount; will always remain zero if boat damage is not enabled
waveHeight	Number (metres) or Null	Significant wave height; may be null if wave data is not available at boat position
race	String	Race ID in which the boat is participating
waypointsReached	Number	Number of race waypoints that have been sailed to

Boat Command

Description: Sends a command to the boat (start, stop, adjust course).

Path: /sailnavsim/api/boatcmd.php
Supported methods: POST

URL request parameters:

key - the boat key for which to send the command

Request body: Form values (content-type: application/x-www-form-urlencoded), containing one of the following commands and accompanying value (if applicable for command):

Command ("cmd")	Value ("value")	Description
start	none	Commands the boat to start Example: cmd=start
stop	none	Commands the boat to stop ("sails down") Example: cmd=stop
course	course in compass degrees between 0 and 360, inclusive	Changes desired boat course through water Example: cmd=course&value=90

Response body: A JSON-encoded object indicating the result:

Name	Type (units)	Description
status	String	Command status result; any value other than "ok" means the command was unsuccessful

Race Info

Description: Provides race details for the requested race ID.

Path: /sailnavsim/api/raceinfo.php
Supported methods: GET

URL request parameters:

id - the race ID for which to request data

Response body: A JSON-encoded object, which includes the following values:

Name	Type (units)	Description
startTime	Number (seconds)	Unix epoch time of the start of the race
startLat	Number (degrees)	Starting position latitude in decimal degrees
startLon	Number (degrees)	Starting position longitude in decimal degrees
reportInterval	Number (seconds)	Boat report interval sharing period
boatType	Number	Boat type: SailNavSim Classic Seascape 18 Contessa 25 Hanse 385 Volvo 70 Super Maxi Scallywag 140-foot Brigantine Maxi Trimaran IMOCA 60 Improvised Lifeboat
damageEnabled	Boolean	true if boat damage mode is enabled; false otherwise
finishMinLat	Number (degrees)	Finishing bounding box minimum latitude (SW corner) in decimal degrees
finishMinLon	Number (degrees)	Finishing bounding box minimum longitude (SW corner) in decimal degrees
finishMaxLat	Number (degrees)	Finishing bounding box maximum latitude (NE corner) in decimal degrees
finishMaxLon	Number (degrees)	Finishing bounding box maximum longitude (NE corner) in decimal degrees
waypoints	Array	Provides race waypoint details as an array of WaypointBox objects (see below)
boats	Object	Provides the most recent "shared" reports for all boats in the race as an object containing BoatReportDetail objects (see below) as values, keyed by the boat's name/alias (String)

WaypointBox Object:

Name Type (units) Description

minLat Number (degrees) Waypoint bounding box minimum latitude (SW corner) in decimal degrees

minLon Number (degrees) Waypoint bounding box minimum longitude (SW corner) in decimal degrees

maxLat Number (degrees) Waypoint bounding box maximum latitude (NE corner) in decimal degrees

maxLon Number (degrees) Waypoint bounding box maximum longitude (NE corner) in decimal degrees

BoatReportDetail Object:

Name Type (units) Description

lat Number (degrees) Boat's reported position latitude in decimal degrees

lon Number (degrees) Boat's reported position longitude in decimal degrees

speedGround Number (metres/second) Boat's reported speed over ground (SOG)

reportTime Number (seconds) Unix epoch time of the most recent report for this boat

finishTime Number (seconds) or Null Unix epoch time when the boat finished the race; will be null if boat has not yet finished

isActive Boolean true if boat is active and controllable; false if boat has been deactivated due to inactivity

Name	Type (units)	Description
minLat	Number (degrees)	Waypoint bounding box minimum latitude (SW corner) in decimal degrees
minLon	Number (degrees)	Waypoint bounding box minimum longitude (SW corner) in decimal degrees
maxLat	Number (degrees)	Waypoint bounding box maximum latitude (NE corner) in decimal degrees
maxLon	Number (degrees)	Waypoint bounding box maximum longitude (NE corner) in decimal degrees

Name	Type (units)	Description
lat	Number (degrees)	Boat's reported position latitude in decimal degrees
lon	Number (degrees)	Boat's reported position longitude in decimal degrees
speedGround	Number (metres/second)	Boat's reported speed over ground (SOG)
reportTime	Number (seconds)	Unix epoch time of the most recent report for this boat
finishTime	Number (seconds) or Null	Unix epoch time when the boat finished the race; will be null if boat has not yet finished
isActive	Boolean	true if boat is active and controllable; false if boat has been deactivated due to inactivity

Public Races

Description: Provides the current set of upcoming public races.

Path: /sailnavsim/api/public_races.php
Supported methods: GET

URL request parameters: none

Response body: A JSON-encoded object, containing PublicRaceDetail objects (see below) as values, keyed by the race ID (String) of each race.

PublicRaceDetail Object:

Name Type (units) Description

name String Race name

description String Race description, as provided by the race creator

startTime Number (seconds) Unix epoch time of the start of the race

Name	Type (units)	Description
name	String	Race name
description	String	Race description, as provided by the race creator
startTime	Number (seconds)	Unix epoch time of the start of the race

WebSocket

Description: Provides a stream of "live" data updates, once per second, of your boat's position and speed.

WebSocket Endpoint Path: /sailnavsim/snsws/v1/ws

Request message: A single JSON-encoded WebSocketRequest object (see below). Any data other than a valid request message for a valid and active boat key will result in the WebSocket being disconnected by the server. Currently each WebSocket connection supports providing data for only a single boat.

WebSocketRequest Object:

Name Type (units) Description

cmd String The requested command:

bdl - for requesting live boat data (a stream of BoatDataLiveResponse messages)

key String A valid boat key for an active boat

Name	Type (units)	Description
cmd	String	The requested command: *bdl* - for requesting live boat data (a stream of BoatDataLiveResponse messages)
key	String	A valid boat key for an active boat

Response messages: JSON-encoded objects, each a BoatDataLiveResponse object (see below).

BoatDataLiveResponse Object:

Name Type (units) Description

lat Number (degrees) Boat position latitude in decimal degrees

lon Number (degrees) Boat position longitude in decimal degrees

ctw Number (degrees) Boat course (compass degrees true) through water

stw Number (metres/second) Boat speed through water

cog Number (degrees) Boat course (compass degrees true) over ground

sog Number (metres/second) Boat speed over ground