At OpenGolfSim, we believe in being as transparent and developer friendly as possible. We think this helps grow an active and engaged community and empowers more users to build cool things.

Below you’ll find documentation for our developer API. It’s still in the early stages, so check back often for updates.

Have a feature or API idea? Want to nerd out? Come drop us a line on our Discord, we’d love to see what you’re building!

  1. TCP Connection
  2. Commands
    1. Device Status
    2. Shot Data
  3. Events
    1. Player Update
    2. Shot Result
      1. type
      2. unit

TCP Connection

Our Developer API allows for simple TCP communication on port 3111 to communicate with the OpenGolfSim app programmatically. This makes it easy to create your own experimental integrations, launch monitor connectors, or other custom automation.

If connecting over the network, you can also use the local IP of your machine (e.g. 192.168.x.x)

Once you’ve established a connection, you can send and receive messages to interact with the API. See our example code to get an idea of how to connect.

Commands

Below is a list of the commands and payloads that can be sent to the OpenGolfSim API. Messages are JSON formatted payloads sent over the TCP connection.

Device Status

You can indicate the device’s status by sending a ready or busy event type.

An example payload for indicating a launch monitor is ready to receive shots:

{
  "type": "device",
  "status": "ready"
}

An example payload for indicating a launch monitor is busy:

{
  "type": "device",
  "status": "busy"
}

Shot Data

Clients can send the follow shot data measurements to simulate or record a shot in OpenGolfSim.

  • type
    • shot - The message type for shots
  • unit
    • imperial - (default) Indicates the speed values are in miles per hour
    • metric - Indicates the speed is supplied in meters per second
  • shot
    • ballSpeed - The ball speed in miles per hour (imperial) or meters per second (metric)
    • verticalLaunchAngle - The vertical launch angle of the shot. Should be between 0° and 45°
    • horizontalLaunchAngle - The horizontal launch angle of the shot. Should be between -45° and 45°
    • spinSpeed - The ball spin speed in rotations per minute (RPM)
    • spinAxis - Spin axis. Values should be between -45° and 45°

Note: If no unit is supplied, then imperial (MPH) will be assumed.

An example payload for a shot in MPH:

{
  "type": "shot",
  "shot": {
    "ballSpeed": 101.2,
    "verticalLaunchAngle": 15.4,
    "horizontalLaunchAngle": -2.1,
    "spinSpeed": 3021,
    "spinAxis": -0.5
  }
}

An example payload for a shot in metric units:

{
  "type": "shot",
  "unit": "metric",
  "shot": {
    "ballSpeed": 44.704,
    "verticalLaunchAngle": 15.4,
    "horizontalLaunchAngle": -2.1,
    "spinSpeed": 3021,
    "spinAxis": -0.5
  }
}

Events

The API server will send JSON formatted messages over the TCP connection, which you can read and process for your own project. Below is a list of the events that are sent to any active TCP connection.

Player Update

Player updates are sent any time a player or player property like the current club is changed.

  • type - The event type is player

  • data - The player update data

    • playerId - The unique player ID
    • currentPosition - The players current global position on the map.
    • club - The players current club
      • name - The club name
      • id - The two letter club identifier
      • distance - The user setting for this club’s distance in meters
{
  "type": "player",
  "data": {
    "playerId": "b79b745b-e643-4b28-be4e-f4ad4690907a",
    "currentPosition": {"x":0,"y":0,"z":0},
    "club": {
      "name": "3W",
      "id": "3W",
      "distance": 205
    }
  }
}

Shot Result

When a shot is completed in the simulator, the Developer API will send a result event with some details about the shot. Note that at the time of writing result data will always be stored/sent in meters.

type

  • result - The message type for shots

unit

  • imperial - (default) Indicates the speed values are in miles per hour
{
  "type": "result",
  "data": {
    "result": {
      "carry": 196.06776428222656,
      "height": 18.728025436401367,
      "roll": 6.482479572296143,
      "total": 202.54876708984375,
      "lateral": -0.07558325678110123
    },
    "club": {
      "name": "5W",
      "id": "5W",
      "distance": 205
    },
    "shot": {
      "ballSpeed": 135,
      "verticalLaunchAngle": 11.100000381469727,
      "horizontalLaunchAngle": 1.2000000476837158,
      "spinAxis": -2.5,
      "spinSpeed": 4800
    },
    "sessionId": 22
  }
}

Table of contents