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. Events
    1. Shot Result
    2. Player Change
  3. Code Examples

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.

Host 127.0.0.1
Port 3111

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 JSON payloads to interact with the API.

Events

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

Shot Result

After a shot has been completed in OpenGolfSim Core connected sockets will receive a result event with some stats about the shot from the simulator. This is useful for displaying or recording shot data in your own application.

{
  "type": "result",
  "result": {
    "carry": 220.0,
    "total": 221.5,
    "roll": 1.5,
    "height": 48.1
  },
  "shot": {
    "ballSpeed": 128.5,
    "horizontalLaunchAngle": 2.4,
    "verticalLaunchAngle": 2.4,
    "spinSpeed": 2002,
    "spinAxis": -1.2
  }
}

Player Change

When a new player is up, this event will fire and include some details about the player’s current state in the game.

{
  "type": "player",
  "player": {
    "name": "Fry",
    "id": "1234-5678-9101-11"
  },
  "state": {
    "score": 8,
    "hole": 4,
    "distanceToPin": 224
  }
}

Code Examples

Here are a couple code examples, to give you a better idea of how to send and receive data:

  • const net = require('net');

const PORT = 3111;
const ADDRESS = '127.0.0.1';

const client = new net.Socket();

function sendData(data) {
  client.write(JSON.stringify(data));
}

client.connect(PORT, ADDRESS, () => {
  console.log('Connected to OpenGolfSim!');

  // send device ready
  console.log('Sending device ready event...');
  sendData({
    type: 'device',
    status: 'ready'
  });

  console.log('Sending test shot...');
  // send a shot
  sendData({
    type: 'shot',
    shot: {
      ballSpeed: 135.0, // mph
      verticalLaunchAngle: 11.1, // degrees
      horizontalLaunchAngle: 1.2, // degrees
      spinAxis: -2.5, // degrees, positive = hook/left, negative = slice/right
      spinSpeed: 4800 // ball RPM 
    }
  });

});

client.on('data', (data) => {
  console.log('Received data from OpenGolfSim: ' + data);
});

client.on('close', () => {
  console.log('Connection was closed');
});

  • import socket
import json

def sendData(sock, payload):
  payload_bytes = (json.dumps(payload) + '\n').encode('utf-8')
  sock.sendall(payload_bytes)
  print(f"Sent: {payload_bytes}")


def main():
    host = '127.0.0.1'  # or replace with your server's IP
    port = 3111

    with socket.create_connection((host, port)) as sock:
        # Send device ready event
        sendData(sock, {
          "type": "device",
          "status": "ready"          
        })
        
        # Send shot data event
        sendData(sock, {
          "type": "shot",
          "shot": {
            "ballSpeed": 135.0,
            "verticalLaunchAngle": 11.1,
            "horizontalLaunchAngle": 1.2,
            "spinAxis": -2.5,
            "spinSpeed": 4800
          }
        })

        buffer = ''
        while True:
            data = sock.recv(4096)
            if not data:
                break
            buffer += data.decode('utf-8')

            # Handle multiple messages (delimited by '\n')
            while '\n' in buffer:
                msg, buffer = buffer.split('\n', 1)
                if msg.strip():
                    try:
                        json_msg = json.loads(msg)
                        print(f"Received JSON: {msg}")
                    except json.JSONDecodeError:
                        print(f"Received non-JSON: {msg}")

if __name__ == "__main__":
    main()

Table of contents