Protos Personal Performance - Developers

Home

Information

Club Map

Club Search

Members

Protos Personal Performance has opened up the API that mobile clients can use to post scorecards. This means developers are free to create mobile golf scorecard solutions that can retrieve course details (including center green coordinates) and upload a completed scorecard. Once the scorecard is posted, the member's golf handicap is recomputed and returned to the mobile client.
The queries are HTTP based. The requests are like any other HTML form post, and the response is returned as XML. Processing XML on a mobile device can be a challenge. The Protos JME (Java Mobile Edition) client uses an XML Pull technique. More details can be seen at XMLPull.org.

Retrieving a List of Courses

URL	http://protosgolf.com/golf/gateway
Method	POST

Request Header
Key	Value
P3P-Origin	XML_CLIENT
P3P-Request	CL
P3P-User	Valid Protos username

Request Parameters
Key	Value
regex	URL encoded regular expression which is used to match against club names

Response XML Payload

<?xml version="1.0" encoding="UTF-8"?>
<items>	
	<item id="row_0">
		<id>7</id>
		<name>4 Seasons Country Club Full Course</name>
	</item>
	<item id="row_1">
		<id>41</id>
		<name>Allandale Golf Course </name>
	</item>
	<item id="row_2">
		<id>10</id>
		<name>Angus Glen Golf Club South Course - 18</name>
	</item>
</items>

Where the <id> element contains the unique course ID (needed for the course details query) and <name> element is the concatination of the club name and course name.

Retrieving Course Details

URL	http://protosgolf.com/golf/gateway
Method	POST

Request Header
Key	Value
P3P-Origin	XML_CLIENT
P3P-Request	CD
P3P-User	Valid Protos username

Request Parameters
Key	Value
course_id	Unique number identifying the course

Response XML Payload

<?xml version="1.0"?>
<coursedetails>
	<club id="22">
		<name>Bushwood Golf Club</name>
		<address>
			<street>10905 Reesor Rd</street>
			<city>Markham</city>
			<country>Canada</country>
		</address>
	</club>
	<course id="42">
	<name></name>
	<length>18</length>
	<par>0,4,4,4,4,5,4,4,3,5,4,4,4,3,4,4,4,3</par>
	<handicap>1,7,13,11,17,1,9,3,15,5,16,4,2,18,12,14,10,8</handicap>
	<greencenter units="m">0.0,0.0,0.0;0.0,0.0,0.0;0.0,0.0,0.0;0.0,0.0,0.0;0.0,0.0,0.0;0.0,0.0,0.0;0.0,0.0,0.0;0.0,0.0,0.0;0.0,0.0,0.0;0.0,0.0,0.0;0.0,0.0,0.0;0.0,0.0,0.0;0.0,0.0,0.0;0.0,0.0,0.0;0.0,0.0,0.0;0.0,0.0,0.0;0.0,0.0,0.0;0.0,0.0,0.0</greencenter>
	<teeboxes>
		<teebox>
			<name>Gold</name>
			<designation>M</designation>
			<slope>123</slope>
			<rating>70.2</rating>
			<distance units="yd">								
					123.0,400.0,357.0,379.0,287.0,491.0,336.0,410.0,179.0,542.0,351.0,396.0,386.0,184.0,377.0,329.0,311.0,215.0
			</distance>
			</teebox>
			<teebox>
				<name>Blue</name>
				<designation>M</designation>
				<slope>121</slope>
				<rating>69.0</rating>
				<distance units="yd">
					121.0,389.0,348.0,361.0,278.0,475.0,322.0,392.0,165.0,530.0,341.0,381.0,372.0,176.0,368.0,320.0,300.0,200.0
				</distance>
			</teebox>
		</teeboxes>
	</course>
</coursedetails>

Some points to note:

Course name may be blank - this is typical if a club has only a single course.
Course length denotes the number of holes this course has and indicates the number of data elements have such as , , and
Individual hole values for <par>, <handicap> and <distance> are delimited by a comma (,).
Greencenter contains the following data: latitude,longitude,altitude;
This form is repeated for each hole (see course length). Notice a comma (,) delimits the three values, but a semi-colon (;) demarcates coordinates for each hole. The greencenter units attribute identifies the unit of measure used for the altitude - such as ft (feet), yd (yards), m (meters). These coordinates identify the center of the green, not the cup itself.
Teebox designation can be either M (mens) or F (womens).
Teebox distance is the overall distance from the tee to the cup. The unit of measure is given in the distance units attribute - such as ft (feet), yd (yards), m (meters).

Submitting a Scorecard

URL	http://protosgolf.com/golf/gateway
Method	POST

Request Header
Key	Value
P3P-Origin	XML_CLIENT
P3P-Request	PU
P3P-User	Valid Protos username
P3P-User	MD5 hash of the user's password

Request Parameters
Key	Value
course_id	Unique number identifying the course
tournament	true \| false
teebox	Teebox name
designation	M \| F
hole_1	Score for hole 1
hole_2	Score for hole 2
hole_3	Score for hole 3
hole_4	Score for hole 4
hole_5	Score for hole 5
hole_6	Score for hole 6
hole_7	Score for hole 7
hole_8	Score for hole 8
hole_9	Score for hole 9
hole_10	Score for hole 10
hole_11	Score for hole 11
hole_12	Score for hole 12
hole_13	Score for hole 13
hole_14	Score for hole 14
hole_15	Score for hole 15
hole_16	Score for hole 16
hole_17	Score for hole 17
hole_18	Score for hole 18

Response XML Payload

	 <?xml version="1.0"?>
	 <scorecard_update>
	 	<status rc="0"></status>
	 	<handicap username="cvoth">
	 		<display>+4.3R</display>
	 		<value>-4.3</value>
	  </handicap>
	 </scorecard_update>

Some points to note:

The status rc (return code) attribute should be zero (0) for a successful submission. If it is not zero, then the <handicap> element will not be present in the response. Also if it is not zero and error message will be provided as text nested by .
Handicap is return as both a displayable string in <display> and as a raw number in <value>.