Introduction
This documents an HTTP based API for basic control of ProPresenter-Scoreboard.
Requests
Scheme
Requests may be made over HTTP or HTTPS depending on your network settings in ProPresenter-Scoreboard.
Prefix
All request paths are prefixed with /api/0
in addition to the standard URL components for the scheme (https), host, and port.
For an end point with the path /data/data
, the full request would be:
GET https://localhost:8080/api/0/data/data
Authentication
API Access Request:
// HTTP
GET /api/0/data/playlists HTTP/1.1
Host: localhost:8080
Content-Type: application/json
// HTTPS
GET /api/0/data/playlists HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Authorization: Bearer <your unique key here>
// HTTPS
curl -H "Authorization: Bearer <your unique key here>" -X GET https://localhost:8080/api/0/data/scores -k
Access to the API is controlled via API keys. Keys can be managed in ProPresenter-Scoreboard preferences.
The API expects the API key to be passed with all requests via an Authorization header like the following:
Authorization: Bearer <your unique key here>
JSON
POST /api/0/opacity/layer/0 HTTP/1.1
Host: localhost:8080
Content-Type: application/json
{ "value": 0.5 }
Some POST requests can take JSON data as a parameter; these are noted by the sections in the documentation that contain a 'Request Body'. Our API conforms to the JSON 1.0 Specification
HTTP
If JSON is needed for an HTTP request, the folowing should be included in the request:
{ "<requestBodyKey>": <requestBodyValue> }
- NOTE: The above is only an example. Some requests will have more keys/values, but these will be defined in the request body sections of the documentation.
CURL
If JSON is needed for a cURL request, the following should be included in the request:
-d '{ "<requestBodyKey>":<requestBodyValue> }' -H "Content-Type: application/json"
- NOTE: The correct "requestBodyKey" and "requestBodyValue" can be found in the Request Body section of each request that should/can include JSON.
Data
Each sport contains its own scoring properties. Custom sports will be user defined.
Scores
Example Request:
GET /api/0/data/scores HTTP/1.1
Host: localhost:8080
Content-Type: application/json
curl -X GET http://localhost:8080/api/0/data/scores -k
Each return value contians a UUID, sportMode and Version number...
"uuid" : "<unique identifier>"
,
"version" : "1.0"
,
"sportMode" : "<sport name>"
Along with the following properties that define each sport:
JSON response:
Australian Football
{
"sportMode" : "AustralianFootball",
"quarter" : "1",
"sportMode" : "Custom",
"team1Behinds" : "2",
"team1Goals" : "3",
"team1Name" : "Atlanta",
"team1Score" : "20",
"team2Behinds" : "3",
"team2Goals" : "4",
"team2Name" : "Boston",
"team2Score" : "27"
}
- quarter
- team1Behinds
- team1Goals
- team1Name
- team1Score
- team2Behinds
- team2Goals
- team2Name
- team2Score
Baseball
{
"sportMode" : "Baseball",
"balls" : "1",
"errors" : "1",
"hits" : "5",
"inning" : "5",
"outs" : "0",
"period" : "1",
"possession" : 1,
"runs" : "2",
"strikes" : "0"
"topBottom" : "T"
"teamOneRuns" : "3"
"teamOneErrors" : "2"
"teamOneHits" : "4"
"teamOneLineScore1" : "0"
"teamOneLineScore2" : "0"
"teamOneLineScore3" : "3"
"teamOneLineScore4" : ""
"teamOneLineScore5" : ""
"teamOneLineScore6" : ""
"teamOneLineScore7" : ""
"teamOneLineScore8" : ""
"teamOneLineScore9" : ""
"teamTwoRuns" : "4"
"teamTwoErrors" : "0"
"teamTwoHits" : "3"
"teamTwoLineScore1" : "0"
"teamTwoLineScore2" : "2"
"teamTwoLineScore3" : "2"
"teamTwoLineScore4" : ""
"teamTwoLineScore5" : ""
"teamTwoLineScore6" : ""
"teamTwoLineScore7" : ""
"teamTwoLineScore8" : ""
"teamTwoLineScore9" : ""
}
- balls
- errors
- hits
- inning
- outs
- possession
- runs
- strikes
- topBottom ("T" or "B")
- teamOneRuns
- teamOneErrors
- teamOneHits
- teamOneLineScore1
- teamOneLineScore2
- teamOneLineScore3
- teamOneLineScore4
- teamOneLineScore5
- teamOneLineScore6
- teamOneLineScore7
- teamOneLineScore8
- teamOneLineScore9
- teamTwoRuns
- teamTwoErrors
- teamTwoHits
- teamTwoLineScore1
- teamTwoLineScore2
- teamTwoLineScore3
- teamTwoLineScore4
- teamTwoLineScore5
- teamTwoLineScore6
- teamTwoLineScore7
- teamTwoLineScore8
- teamTwoLineScore9
Basketball
{
"sportMode" : "Basketball",
"period" : "2",
"possession" : 0,
"sportMode" : "Basketball",
"team1Bonus1" : false,
"team1Bonus2" : false,
"team1Fouls" : "4",
"team1Score" : "6",
"team1TimeOuts" : "3",
"team2Bonus1" : true,
"team2Bonus2" : true,
"team2Fouls" : "0",
"team2Score" : "0",
"team2TimeOuts" : "3"
}
- period
- possession
- team1Bonus1
- team1Bonus2
- team1Fouls
- team1Score
- team1TimeOuts
- team2Bonus1
- team2Bonus2
- team2Fouls
- team2Score
- team2TimeOuts
Football
{
"sportMode" : "Football",
"ballLocation" : "33",
"down" : "3",
"period" : "3",
"possession" : 1,
"team1Score" : "24",
"team1TimeOuts" : "2",
"team2Score" : "12",
"team2TimeOuts" : "1",
"toGo" : "7"
}
- ballLocation
- down
- period
- possession
- team1Score
- team1TimeOuts
- team2Score
- team2TimeOuts
- toGo
Hockey
{
"sportMode" : "Hockey",
"period" : "2",
"team1Saves" : "5",
"team1Score" : "2",
"team1Shots" : "2",
"team1TimeOuts" : "3",
"team2Saves" : "2",
"team2Score" : "1",
"team2Shots" : "3",
"team2TimeOuts" : "3"
}
- period
- team1Saves
- team1Score
- team1Shots
- team1TimeOuts
- team2Saves
- team2Score
- team2Shots
- team2TimeOuts
Lacrosse
{
"sportMode" : "Lacrosse",
"period" : "2",
"possession" : 0,
"team1Saves" : "5",
"team1Score" : "2",
"team1Shots" : "2",
"team1TimeOuts" : "3",
"team2Saves" : "2",
"team2Score" : "1",
"team2Shots" : "3",
"team2TimeOuts" : "3"
}
- period
- possession
- team1Saves
- team1Score
- team1Shots
- team1TimeOuts
- team2Saves
- team2Score
- team2Shots
- team2TimeOuts
Soccer
{
"sportMode" : "Soccer",
"extraTime" : "3",
"period" : "2",
"team1Corner" : "5",
"team1Saves" : "1",
"team1Score" : "4",
"team1Shots" : "3",
"team1TimeOuts" : "3",
"team2Corner" : "1",
"team2Saves" : "0",
"team2Score" : "1",
"team2Shots" : "0",
"team2TimeOuts" : "3"
}
- extraTime
- period
- team1Corner
- team1Saves
- team1Score
- team1Shots
- team1TimeOuts
- team2Corner
- team2Saves
- team2Score
- team2Shots
- team2TimeOuts
Tennis
{
"sportMode" : "Tennis",
"currentSet" : 4,
"period" : "4",
"possession" : 1,
"team1Games" : "0",
"team1Score" : "0",
"team1Set1" : "2",
"team1Set2" : "1",
"team1Set3" : "4",
"team1Set4" : "0",
"team1Set5" : " ",
"team1Set6" : " ",
"team1Set7" : " ",
"team1Set8" : " ",
"team1Set9" : " ",
"team1Sets" : "2",
"team1TimeOuts" : "1",
"team2Games" : "0",
"team2Score" : "0",
"team2Set1" : "4",
"team2Set2" : "0",
"team2Set3" : "0",
"team2Set4" : "0",
"team2Set5" : " ",
"team2Set6" : " ",
"team2Set7" : " ",
"team2Set8" : " ",
"team2Set9" : " ",
"team2Sets" : "1",
"team2TimeOuts" : "3"
}
- currentSet
- period
- possession
- team1Games
- team1Score
- team1Set1
- team1Set2
- team1Set3
- team1Set4
- team1Set5
- team1Set6
- team1Set7
- team1Set8
- team1Set9
- team1Sets
- team1TimeOuts
- team2Games
- team2Score
- team2Set1
- team2Set2
- team2Set3
- team2Set4
- team2Set5
- team2Set6
- team2Set7
- team2Set8
- team2Set9
- team2Sets
- team2TimeOuts
Volleyball
{
"sportMode" : "Volleyball",
"currentSet" : 4,
"period" : "4",
"possession" : 0,
"sportMode" : "Volleyball",
"team1Games" : "2",
"team1Score" : "0",
"team1Set1" : "24",
"team1Set2" : "24",
"team1Set3" : "21",
"team1Set4" : "0",
"team1Set5" : "0",
"team1Set6" : " ",
"team1Set7" : " ",
"team1Set8" : " ",
"team1Set9" : " ",
"team1TimeOuts" : "0",
"team2Games" : "1",
"team2Score" : "0",
"team2Set1" : "18",
"team2Set2" : "21",
"team2Set3" : "24",
"team2Set4" : "0",
"team2Set5" : "0",
"team2Set6" : " ",
"team2Set7" : " ",
"team2Set8" : " ",
"team2Set9" : " ",
"team2TimeOuts" : "0"
}
- currentSet
- possession
- team1Games
- team1Score
- team1Set1
- team1Set2
- team1Set3
- team1Set4
- team1Set5
- team1Set6
- team1Set7
- team1Set8
- team1Set9
- team1TimeOuts
- team2Games
- team2Score
- team2Set1
- team2Set2
- team2Set3
- team2Set4
- team2Set5
- team2Set6
- team2Set7
- team2Set8
- team2Set9
- team2TimeOuts
Custom
{
"sportMode" : "Custom",
"game1" : {
"possession" : "0",
"quarter" : "1",
"team1Goals" : "5",
"team1Name" : "Atlanta",
"team1Saves" : "0",
"team1TimeOuts" : "0",
"team2Goals" : "1",
"team2Name" : "Boston",
"team2Saves" : "0",
"team2TimeOuts" : "0"
},
"game2" : {
"possession" : "0",
"quarter" : "1",
"team1Goals" : "1",
"team1Name" : "Team 3",
"team1Saves" : "0",
"team1TimeOuts" : "0",
"team2Goals" : "4",
"team2Name" : "Team 4",
"team2Saves" : "0",
"team2TimeOuts" : "0"
}
}
In the case of Custom
, the score properties are defined by the user. In this example,
the score properties are:
Goals
, Saves
, Time Outs
- NOTE: If
isGrouped
is selected in the Custom Settings and there is more then one grouping, the score properties will be placed in a sub-array of game values where the key of each game =game
+<ordered number>
Errors
The API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request was invalid. |
401 | Unauthorized -- Authorization failed. |
403 | Forbidden -- The endpoint requested is hidden for administrators only. |
404 | Not Found -- The specified endpoint could not be found. |
405 | Method Not Allowed -- You tried to access an endpoint with an invalid method. |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |