Start | Races | Maps | Help | API | GitHub | Twitter | 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)Description
timeNumber (seconds)Unix epoch time of this boat log report
latNumber (degrees)Boat position latitude in decimal degrees
lonNumber (degrees)Boat position longitude in decimal degrees
courseWaterNumber (degrees)Boat course through water
speedWaterNumber (metres/second)Boat speed through water
trackGroundNumber (degrees)Boat track over ground
speedGroundNumber (metres/second)Boat speed over ground (SOG)
windDirNumber (degrees)Compass direction from which the true wind is blowing
windSpeedNumber (metres/second)Wind speed
windGustNumber (metres/second)Wind gust speed
oceanCurrentDirNumber (degrees) or NullCompass 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 NullOcean surface current speed; may be null if ocean data is not available at boat position
oceanIceNumber (percent) or NullSea ice concentration; may be null if ocean data is not available at boat position
distanceTravelledNumber (metres)Total distance the boat has travelled
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 position
raceStringRace ID in which the boat is participating
waypointsReachedNumberNumber 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: 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

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
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)
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.

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:
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