Steps to establish a Player Session¶

An autheticated user with the right access token can start a Player Session using below steps.

1. Get the list of Bays¶

To start a Session, client application should pass a valid bay Id and optional target Id. Use the get bays API call to read the list of bays.

GET /api/bays

Host: https://localsite.trackmanrange.com

A successful response will look like the following example:

{
  "items": [
    {
      "name": "Bay no. 1 - cloud",
      "description": "This is the first bay on the left corner, ground floor of Driving Range.",
      "worldLocation": {
        "altitude": 72.767,
        "lat": 51.3454345,
        "lon": 10
      },
      "isDynamic" : "false",
      "siteLocation": {
        "x": 0,
        "y": 0,
        "z": 0
      },
      "id": "9279bee1-631b-4bc2-a5b8-62eeeeca9e5d",
      "createdAt": "2016-11-15T09:05:21.789Z",
      "lastUpdatedAt": "2016-11-15T09:05:21.836Z",
      "_links": {
        "self": {
          "method": "GET",
          "href": "https://localsite.trackmanrange.com/api/bays/9279bee1-631b-4bc2-a5b8-62eeeeca9e5d"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "method": "GET",
      "href": "https://localsite.trackmanrange.com/api/bays"
    }
  }
}

The items collection should be used to present user with a collection of bays to select from. The id field of the selected item should be used to create player session.

Note

Above link returns list of fixed as well as dynamic bays in same items collection. To differentiate the fixed bays with dynamic ones use the isDynamic flag on the bay object.

To get list of only fixed bays use below API call. This link can be retrieved using the fixed_bays key from _links of /api endpoint response.

GET /api/bays?type=fixed

To get list of only dynamic bays use below API call. This link can be retrieved using the dynamic_bays key from _links of /api endpoint response.

GET /api/bays?type=dynamic

Response format for both the end points above is the same as /api/bays

Note

Do not hardcode the bays endpoint. Get the bays link by doing an initial request to /api.

2. Get the list of Targets¶

Optionally, Pass the target id to create new player session. Use the get targets API call to read the list of targets.

GET /api/targets

Host: https://localsite.trackmanrange.com

A successful response will look like the following example:

{
  "items": [
    {
      "name": "Target 1",
      "description": "Target in the center",
      "worldCoordinate": {
        "altitude": 72.678,
        "lat": 51.686786,
        "lon": 41
      },
      "id": "ce72011e-030d-46db-b6b4-21829b7a5502",
      "createdAt": "2016-11-15T11:57:43.527Z",
      "lastUpdatedAt": "2016-11-15T11:57:43.527Z",
      "_links": {
        "self": {
          "method": "GET",
          "href": "https://localsite.trackmanrange.com/api/targets/ce72011e-030d-46db-b6b4-21829b7a5502"
        }
      }
    },
    {
      "name": "Target 2",
      "description": "Target in the right corner",
      "worldCoordinate": {
        "altitude": 72.5678,
        "lat": 51.25546,
        "lon": 41
      },
      "id": "6a6b9ae2-d06b-4e21-bc36-0a2b8b33ee92",
      "createdAt": "2016-11-15T11:58:33.537Z",
      "lastUpdatedAt": "2016-11-15T11:58:33.537Z",
      "_links": {
        "self": {
          "method": "GET",
          "href": "https://localsite.trackmanrange.com/api/targets/6a6b9ae2-d06b-4e21-bc36-0a2b8b33ee92"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "method": "GET",
      "href": "https://localsite.trackmanrange.com/api/targets"
    },
    "first": {
      "method": "GET",
      "href": "https://localsite.trackmanrange.com/api/targets"
    },
    "last": {
      "method": "GET",
      "href": "https://localsite.trackmanrange.com/api/targets"
    }
  },
  "page": 1,
  "pageSize": 25,
  "pageCount": 1,
  "total": 2
}

The items collection should be used to present user with a collection of targets to select from. The id field of the selected item should be used to create player session.

Note

Do not hardcode the targets endpoint. Get the targets link by doing an initial request to /api.

3. Get the list of Clubs¶

Use the clubs API endpoint to get a list of clubs.

GET /api/clubs

Host: https://localsite.trackmanrange.com

Or preferably use the clubs link from the /api response.

A successful response will look like the following example:

{
  "items": [
    {
      "id": "p",
      "name": "Putter",
      "shortName": "p",
      "type": "Putter"
    },
    {
      "id": "1i",
      "name": "1 Iron",
      "shortName": "1i",
      "type": "Iron"
    },
    {
      "id": "2i",
      "name": "2 Iron",
      "shortName": "2i",
      "type": "Iron"
    },
    {
      "id": "3i",
      "name": "3 Iron",
      "shortName": "3i",
      "type": "Iron"
    },
    {
      "id": "4i",
      "name": "4 Iron",
      "shortName": "4i",
      "type": "Iron"
    },
    {
      "id": "5i",
      "name": "5 Iron",
      "shortName": "5i",
      "type": "Iron"
    },
    {
      "id": "6i",
      "name": "6 Iron",
      "shortName": "6i",
      "type": "Iron"
    },
    {
      "id": "7i",
      "name": "7 Iron",
      "shortName": "7i",
      "type": "Iron"
    },
    {
      "id": "8i",
      "name": "8 Iron",
      "shortName": "8i",
      "type": "Iron"
    },
    {
      "id": "9i",
      "name": "9 Iron",
      "shortName": "9i",
      "type": "Iron"
    },
    {
      "id": "Dr",
      "name": "Driver",
      "shortName": "Dr",
      "type": "Wood"
    },
    {
      "id": "2w",
      "name": "2 Wood",
      "shortName": "2w",
      "type": "Wood"
    },
    {
      "id": "3w",
      "name": "3 Wood",
      "shortName": "3w",
      "type": "Wood"
    },
    {
      "id": "4w",
      "name": "4 Wood",
      "shortName": "4w",
      "type": "Wood"
    },
    {
      "id": "5w",
      "name": "5 Wood",
      "shortName": "5w",
      "type": "Wood"
    },
    {
      "id": "6w",
      "name": "6 Wood",
      "shortName": "6w",
      "type": "Wood"
    },
    {
      "id": "7w",
      "name": "7 Wood",
      "shortName": "7w",
      "type": "Wood"
    },
    {
      "id": "8w",
      "name": "8 Wood",
      "shortName": "8w",
      "type": "Wood"
    },
    {
      "id": "9w",
      "name": "9 Wood",
      "shortName": "9w",
      "type": "Wood"
    },
    {
      "id": "PW",
      "name": "Pitching Wedge",
      "shortName": "PW",
      "type": "Wedge"
    },
    {
      "id": "SW",
      "name": "Sand Wedge",
      "shortName": "SW",
      "type": "Wedge"
    },
    {
      "id": "LW",
      "name": "Lob Wedge",
      "shortName": "LW",
      "type": "Wedge"
    },
    {
      "id": "50",
      "name": "50° Wedge",
      "shortName": "50°",
      "type": "Wedge"
    },
    {
      "id": "52",
      "name": "52° Wedge",
      "shortName": "52°",
      "type": "Wedge"
    },
    {
      "id": "54",
      "name": "54° Wedge",
      "shortName": "54°",
      "type": "Wedge"
    },
    {
      "id": "56",
      "name": "56° Wedge",
      "shortName": "56°",
      "type": "Wedge"
    },
    {
      "id": "58",
      "name": "58° Wedge",
      "shortName": "58°",
      "type": "Wedge"
    },
    {
      "id": "60",
      "name": "60° Wedge",
      "shortName": "60°",
      "type": "Wedge"
    },
    {
      "id": "1h",
      "name": "1 Hybrid",
      "shortName": "1h",
      "type": "Hybrid"
    },
    {
      "id": "2h",
      "name": "2 Hybrid",
      "shortName": "2h",
      "type": "Hybrid"
    },
    {
      "id": "3h",
      "name": "3 Hybrid",
      "shortName": "3h",
      "type": "Hybrid"
    },
    {
      "id": "4h",
      "name": "4 Hybrid",
      "shortName": "4h",
      "type": "Hybrid"
    },
    {
      "id": "5h",
      "name": "5 Hybrid",
      "shortName": "5h",
      "type": "Hybrid"
    },
    {
      "id": "6h",
      "name": "6 Hybrid",
      "shortName": "6h",
      "type": "Hybrid"
    },
    {
      "id": "7h",
      "name": "7 Hybrid",
      "shortName": "7h",
      "type": "Hybrid"
    },
    {
      "id": "8h",
      "name": "8 Hybrid",
      "shortName": "8h",
      "type": "Hybrid"
    },
    {
      "id": "9h",
      "name": "9 Hybrid",
      "shortName": "9h",
      "type": "Hybrid"
    }
  ],
  "_links": {
    "self": {
      "method": "GET",
      "href": "https://localsite.trackmanrange.com/api/clubs"
    }
  }
}

You can restrict the returned clubs to a specific category by specifying the type query string parameter:

GET /api/clubs?type=Hybrid

Host: https://localsite.trackmanrange.com

You can get a list of the available club types from the following API endpoint or from the club_types link in /api:

GET /api/clubs/types

Host: https://localsite.trackmanrange.com

{
  "items": [
    "Putter",
    "Iron",
    "Wood",
    "Wedge",
    "Hybrid"
  ],
  "_links": {
    "self": {
      "method": "GET",
      "href": "https://localsite.trackmanrange.com/api/clubs/types"
    }
  }
}

4. Create Player Session¶

To create a new Player Session, use the following API call passing a bay id, optional target id and information about the client app that calls the API. This section now refers to creating player session with fixed bays. For dynamic bay scenario refer to page Claim Dynamic Bay

POST /api/session

{
 "bayId": "9279bee1-631b-4bc2-a5b8-62eeeeca9e5d",
 "targetId": "a43a1e52-180a-4519-95e2-373a5afff414",
 "clientInfo": {
    "appName": "RangeApp",
    "appVersion": "1.1.0",
    "deviceId": "<unique device id>",
    "deviceModel": "iPhone 7",
    "osVersion": "iOS 10",
    "platform": "iOS"
  }
}

Host: https://localsite.trackmanrange.com

A successful response will look like the following example:

{
  "sessionId": "719167b8-d395-4d66-bccc-413896130cef",
  "player": {
    "id": "5be86359-073c-434b-ad2d-a3932222dabe",
    "name": "Example Player"
  },
  "bayId": "9279bee1-631b-4bc2-a5b8-62eeeeca9e5d",
  "targetId": "a43a1e52-180a-4519-95e2-373a5afff414",
  "startedAt": "2016-11-16T09:54:48.8456444Z",
  "_links": {
    "self": {
      "method": "GET",
      "href": "https://localsite.trackmanrange.com/api/session"
    },
    "endsession": {
      "method": "DELETE",
      "href": "https://localsite.trackmanrange.com/api/session"
    },
    "keepalive": {
      "method": "POST",
      "href": "https://localsite.trackmanrange.com/api/session/keepalive"
    },
    "select_target": {
      "method": "PUT",
      "href": "https://localsite.trackmanrange.com/api/session/target"
    },
    "measurements": {
      "method": "GET",
      "href": "ws://dr-site-dev-test.azurewebsites.net/ws?type=measurements&sessionId=719167b8-d395-4d66-bccc-413896130cef&ticketId=6ca4e7db-e6d6-49da-b4e4-1ae1126ed433"
    },
    "general_notifications": {
      "method": "GET",
      "href": "ws://dr-site-dev-test.azurewebsites.net/ws?type=general&sessionId=719167b8-d395-4d66-bccc-413896130cef&ticketId=6ca4e7db-e6d6-49da-b4e4-1ae1126ed433"
    },
    "ticket": {
      "method": "POST",
      "href": "https://localsite.trackmanrange.com/api/tickets"
    }
  }
}

A successful call to the API returns a session id. If the user session is already in progress, it returns the existing session id.

Additionally the response contains links

Use the measurements link to open a channel to start receiving the shot measurements.
Use the general_notifications link to open a channel to start receiving session-related event notifications. For more details on the different notification types refer to the Notifications section.
Use the endsession link to end the current player session.
Use the keepalive link to prevent the session from timing out during long periods of player inactivity.
Use the select_target link to select another target after the session has started.

[SE00001] error code is returned if the bay is occupied by another player.

Note

Do not hardcode the session endpoint. Get the create_session link by doing an initial request to /api.

5. Receive Measurements¶

To start receiveing measurements establish a Web Socket connection using the measurements link provided by the create player session response.

Below example is using standard HTML5, ES6 WebSocket.

var socket = new WebSocket('ws://dr-site-dev-test.azurewebsites.net/ws?type=measurements&sessionId=719167b8-d395-4d66-bccc-413896130cef&ticketId=6ca4e7db-e6d6-49da-b4e4-1ae1126ed433');

On successful connection client application can subscribe to the web socket events to receive messages.

socket.onopen = function () {
  console.log('Client is connected to the server');
};

socket.onclose = function () {
  console.log('Disconnected.');
};

socket.onmessage = function (e) {
  console.log('Received a message.');
};

6. Change Targets¶

A target can be specified upon creating a new session or at any point while a session is in progress.

To change the target while a session has started:

PUT /api/session/target

{
  "targetId": "212de4c7-04f9-44aa-95c1-54a74a92f1fa"
}

Host: https://localsite.trackmanrange.com

where targetId is a valid target identifier. To deselect the current target just call the same endpoint without a body or with a null or empty targetId:

PUT /api/session/target

Host: https://localsite.trackmanrange.com

Note

You can obtain the Url to select a target from the select_target link that is included with the response when creating or retrieving the current player's session.

7. Retrieve the Strokes of the Current Session¶

To get a list of all strokes for the current player session, make a GET request to the strokes link of the current session info object:

GET /api/session/strokes?excludeMeasurements=true

Host: https://localsite.trackmanrange.com

The response is a paged list of strokes, sorted by the stroke time in descending order and it looks like the following json result:

{
  "items": [
    {
      "id": "1a6ad208-b24f-41d5-8330-f966ed6e12c2",
      "targetDistance": 124.1181,
      "bayId": "1ddd2905-b829-4df6-ad19-6be2a5296ee7",
      "bayName": "1",
      "bayPosition": [
        13.537870928842,
        -3.5178784553,
        43.298263960798
      ],
      "teePosition": [
        13.537870928842,
        -3.5178784553,
        43.298263960798
      ],
      "time": "2015-01-16T16:03:21.151877Z",
      "sessionId": "458f78a3-2ac8-492d-b75d-7177a7c15a4f",
      "player": {
        "id": "1fc83daf-f0ba-49f9-a922-777330d0291f",
        "name": "John Doe"
      },
      "targetId": "cbc1de9f-f6b1-456e-b58f-32833848fba8",
      "createdAt": "2017-03-01T13:34:26.9293222Z",
      "lastUpdatedAt": "2017-03-01T13:34:26.931322Z",
      "_links": {
        "self": {
          "method": "GET",
          "href": "https://localsite.trackmanrange.com/api/session/strokes/1a6ad208-b24f-41d5-8330-f966ed6e12c2"
        }
      }
    },
    {
      "id": "b7466d23-4b39-45f7-b0d8-fa19c0bedb50",
      "targetDistance": 123.9662,
      "bayId": "1ddd2905-b829-4df6-ad19-6be2a5296ee7",
      "bayName": "1",
      "bayPosition": [
        13.537870928842,
        -3.5178784553,
        43.298263960798
      ],
      "teePosition": [
        13.537870928842,
        -3.5178784553,
        43.298263960798
      ],
      "time": "2015-02-03T11:45:12.632439Z",
      "sessionId": "458f78a3-2ac8-492d-b75d-7177a7c15a4f",
      "player": {
        "id": "1fc83daf-f0ba-49f9-a922-777330d0291f",
        "name": "John Doe"
      },
      "targetId": "cbc1de9f-f6b1-456e-b58f-32833848fba8",
      "createdAt": "2017-03-01T13:34:23.9627051Z",
      "lastUpdatedAt": "2017-03-01T13:34:24.0377064Z",
      "_links": {
        "self": {
          "method": "GET",
          "href": "https://localsite.trackmanrange.com/api/session/strokes/b7466d23-4b39-45f7-b0d8-fa19c0bedb50"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "method": "GET",
      "href": "https://localsite.trackmanrange.com/api/session/strokes?excludeMeasurements=true"
    },
    "first": {
      "method": "GET",
      "href": "https://localsite.trackmanrange.com/api/session/strokes?excludeMeasurements=true"
    },
    "last": {
      "method": "GET",
      "href": "https://localsite.trackmanrange.com/api/session/strokes?excludeMeasurements=true"
    }
  },
  "page": 1,
  "pageSize": 20,
  "pageCount": 1,
  "total": 2
}

You can then use the self link of each search result to get additional information on each stroke individually.

Alternatively, you can use the strokes_full link of the session object so that the results also include the measurement trajectories as part of the content. with the response when creating or retrieving the current player's session.

8. Claim Bay (dynamic bay scenario)¶

For dynamic bay scenario, bay is not known at the Session creation time. So for playing on green/ dynamic bay requires player hit a shot and confirm the bay specifying it in a PUT api

To select a bay in dynamic bay scenario:

PUT /api/session/bay

{
  "bayId": "212de4c7-04f9-44aa-95c1-54a74a92f1fa"
}

Host: https://localsite.trackmanrange.com

where bayId is a valid bay identifier. Once selected the bay can not be changed for a session, as long as it is in progress.

[SE00003] error code is returned when trying to change bay on an active session.

Note

You can obtain the Url to select a bay from the select_bay link that is included with the response when creating or retrieving the current player's session. This link is only available for dynamic bay session.

For more details refer the page Claim Dynamic Bay.

9. Delete a stroke¶

Delete Stroke API: Stroke can be deleted using below API.

DELETE /api/session/strokes/{strokeId}

Host: https://localsite.trackmanrange.com

where strokdId is the id of the stroke to be deleted.

The link is not available on the websocket measurement. To get the delete link the client app will have to query current sessoin for strokes.

To get a specific stroke appends strokeIds with the specific strokeid to query string, For details, refer to the section above Retrieve the Strokes of the Current Session

GET api/session/strokes?excludemeasurements=true&strokeIds=73ced41d-b3ad-439a-a4f0-2dfc2a89d326

Host: https://localsite.trackmanrange.com

the specific stroke from the collection has a link to delete the shot e.g. Use delete link from links collection

DELETE /api/session/strokes/73ced41d-b3ad-439a-a4f0-2dfc2a89d326

Host: https://localsite.trackmanrange.com