Start | Races | Maps | Help | API | Code | Contact

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.

API Endpoints


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: Response body: A JSON-encoded object, which includes the following values:
NameType (units)DescriptionNotes for celestial navigation mode
timeNumber (seconds)Unix epoch time of this boat log report
latNumber (degrees)Boat position latitude in decimal degreesNot present unless near land or boat has finished
lonNumber (degrees)Boat position longitude in decimal degreesNot present unless near land or boat has finished
courseWaterNumber (degrees)Boat course through waterUses magnetic compass
speedWaterNumber (metres/second)Boat speed through waterUp to 5% random adjustment from true value
trackGroundNumber (degrees)Boat track over groundNot present
speedGroundNumber (metres/second)Boat speed over ground (SOG)Not present
windDirNumber (degrees)Compass direction from which the true wind is blowing; adjusted to take into account local ocean currents if presentUses magnetic compass with additional up to 5 degree random adjustment
windSpeedNumber (metres/second)Wind speed; adjusted to take into account local ocean currents if presentUp to 5% random adjustment from true value
windGustNumber (metres/second)Wind gust speed; adjusted to take into account local ocean currents if presentUp to 5% random adjustment from true value
oceanCurrentDirNumber (degrees) or NullCompass direction towards which the ocean surface current is flowing; may be null if ocean data is not available at boat positionNot present
oceanCurrentSpeed Number (metres/second) or NullOcean surface current speed; may be null if ocean data is not available at boat positionNot present
oceanIceNumber (percent) or NullSea ice concentration; may be null if ocean data is not available at boat positionReported in increments of 10%
distanceTravelledNumber (metres)Total distance the boat has travelledNot present unless boat has finished
damageNumber (percent)Boat damage amount; will always remain zero if boat damage is not enabled
waveHeightNumber (metres) or NullSignificant wave height; may be null if wave data is not available at boat positionUp to 10% random adjustment from true value
raceStringRace ID in which the boat is participating
waypointsReachedNumberNumber of race waypoints that have been sailed toNot 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: 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
startnoneCommands the boat to start
  • Example: cmd=start
stopnoneCommands the boat to stop ("sails down")
  • Example: cmd=stop
coursecourse in compass degrees between 0 and 360, inclusiveChanges desired boat course through water
  • Example: cmd=course&value=90
Note: In celestial navigation mode, this is interpreted as degrees magnetic.

Response body: A JSON-encoded object indicating the result:
NameType (units)Description
statusStringCommand 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: Response body: A JSON-encoded object, which includes the following values:
NameType (units)Description
startTimeNumber (seconds)Unix epoch time of the start of the race
startLatNumber (degrees)Starting position latitude in decimal degrees
startLonNumber (degrees)Starting position longitude in decimal degrees
reportIntervalNumber (seconds)Boat report interval sharing period
boatTypeNumberBoat type:
  1. SailNavSim Classic
  2. Seascape 18
  3. Contessa 25
  4. Hanse 385
  5. Volvo 70
  6. Super Maxi Scallywag
  7. 140-foot Brigantine
  8. Maxi Trimaran
  9. IMOCA 60
  10. Improvised Lifeboat
  11. Volvo 65
  12. AC72
damageEnabledBooleantrue if boat damage mode is enabled; false otherwise
finishMinLatNumber (degrees)Finishing bounding box minimum latitude (SW corner) in decimal degrees
finishMinLonNumber (degrees)Finishing bounding box minimum longitude (SW corner) in decimal degrees
finishMaxLatNumber (degrees)Finishing bounding box maximum latitude (NE corner) in decimal degrees
finishMaxLonNumber (degrees)Finishing bounding box maximum longitude (NE corner) in decimal degrees
waypointsArrayProvides race waypoint details as an array of WaypointBox objects (see below)
boatsObjectProvides 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:
NameType (units)Description
minLatNumber (degrees)Waypoint bounding box minimum latitude (SW corner) in decimal degrees
minLonNumber (degrees)Waypoint bounding box minimum longitude (SW corner) in decimal degrees
maxLatNumber (degrees)Waypoint bounding box maximum latitude (NE corner) in decimal degrees
maxLonNumber (degrees)Waypoint bounding box maximum longitude (NE corner) in decimal degrees

BoatReportDetail Object:
NameType (units)Description
latNumber (degrees)Boat's reported position latitude in decimal degrees
lonNumber (degrees)Boat's reported position longitude in decimal degrees
speedGroundNumber (metres/second)Boat's reported speed over ground (SOG)
Note: This is not present in celestial navigation mode.
reportTimeNumber (seconds)Unix epoch time of the most recent report for this boat
finishTimeNumber (seconds) or NullUnix epoch time when the boat finished the race; will be null if boat has not yet finished
isActiveBooleantrue 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:
NameType (units)Description
nameStringRace name
descriptionStringRace description, as provided by the race creator
startTimeNumber (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:
NameType (units)Description
cmdStringThe requested command:
  • bdl - for requesting live boat data (a stream of BoatDataLiveResponse messages)
keyStringA valid boat key for an active boat


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

BoatDataLiveResponse Object:
NameType (units)Description
latNumber (degrees)Boat position latitude in decimal degrees
lonNumber (degrees)Boat position longitude in decimal degrees
ctwNumber (degrees)Boat course (compass degrees true) through water
stwNumber (metres/second)Boat speed through water
cogNumber (degrees)Boat course (compass degrees true) over ground
sogNumber (metres/second)Boat speed over ground