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 as much as possible to avoid removing any existing capabilities and values and to otherwise continue maintaining 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	Notes for celestial navigation mode
time	Number (seconds)	Unix epoch time of this boat log report
lat	Number (degrees)	Boat position latitude in decimal degrees	Not present unless near land or boat has finished
lon	Number (degrees)	Boat position longitude in decimal degrees	Not present unless near land or boat has finished
courseWater	Number (degrees)	Boat heading and course through water (Basic boat types); boat heading only for Advanced boat types	Uses magnetic compass
speedWater	Number (metres/second)	Boat speed ahead and speed through water (Basic boat types); boat speed ahead only for Advanced boat types	Up to 5% random adjustment from true value
trackGround	Number (degrees)	Boat track/course over ground	Not present
speedGround	Number (metres/second)	Boat speed over ground (SOG)	Not present
windDir	Number (degrees)	Compass direction from which the true wind is blowing; adjusted to take into account local ocean currents if present	Uses magnetic compass with additional up to 5 degree random adjustment
windSpeed	Number (metres/second)	Wind speed; adjusted to take into account local ocean currents if present	Up to 5% random adjustment from true value
windGust	Number (metres/second)	Wind gust speed; adjusted to take into account local ocean currents if present	Up to 5% random adjustment from true value
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	Not present
oceanCurrentSpeed	Number (metres/second) or Null	Ocean surface current speed; may be null if ocean data is not available at boat position	Not present
oceanIce	Number (percent) or Null	Sea ice concentration; may be null if ocean data is not available at boat position	Reported in increments of 10%
distanceTravelled	Number (metres)	Total distance the boat has travelled	Not present unless boat has finished
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	Up to 10% random adjustment from true value
leewaySpeed	Number (metres/second)	Boat velocity abeam (perpendicular to its direction ahead); can only be non-zero for Advanced boat types	Up to 5% random adjustment from true value
heelingAngle	Number (degrees)	Heeling angle of boat; can only be non-zero for Advanced boat types
race	String	Race ID in which the boat is participating
waypointsReached	Number	Number of race waypoints that have been sailed to	Not present (but waypoints boxes still apply)

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 Note: Only for Basic boat types; for Advanced boat types, use the "sail_area" command.
course	course in compass degrees between 0 and 360, inclusive	Changes desired boat course through water Example: cmd=course&value=90 Note: In celestial navigation mode, this is interpreted as degrees magnetic.
sail_area	sail area up in percent between 0 and 100, inclusive	Changes amount of sail exposed to wind Example: cmd=sail_area&value=50 Note: Only for Advanced boat types; for Basic boat types, use the "start" and "stop" commands.

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

Basic boat types:

SailNavSim Classic
Seascape 18
Contessa 25
Hanse 385
Volvo 70
Super Maxi Scallywag
140-foot Brigantine
Maxi Trimaran
IMOCA 60
Improvised Lifeboat
Volvo 65
AC72

Advanced boat types:

Advanced Prototype

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)
Note: This is not present in celestial navigation mode.

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) Note: This is not present in celestial navigation mode.
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. Available only for boats not in celestial navigation mode.

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 (for a boat not in celestial navigation mode) 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) Basic boat types: Boat course (compass degrees true) through water
Advanced boat types: Boat heading (compass degrees true)

stw Number (metres/second) Basic boat types: Boat speed through water
Advanced boat types: Boat speed ahead through water; negative values moving astern, positive values moving ahead

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

sog Number (metres/second) Boat speed over ground

lws Number (metres/second) Basic boat types: Always zero
Advanced boat types: Boat speed abeam through water (leeway); negative values moving to port, positive values moving to starboard

ha Number (degrees) Basic boat types: Always zero
Advanced boat types: Boat heeling angle