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

URLhttp://protosgolf.com/golf/gateway
MethodPOST
Request Header
KeyValue
P3P-OriginXML_CLIENT
P3P-RequestCL
P3P-UserValid Protos username
Request Parameters
KeyValue
regexURL encoded regular expression which is used to match against club names
Response XML Payload
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

URLhttp://protosgolf.com/golf/gateway
MethodPOST
Request Header
KeyValue
P3P-OriginXML_CLIENT
P3P-RequestCD
P3P-UserValid Protos username
Request Parameters
KeyValue
course_idUnique number identifying the course
Response XML Payload

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

URLhttp://protosgolf.com/golf/gateway
MethodPOST
Request Header
KeyValue
P3P-OriginXML_CLIENT
P3P-RequestPU
P3P-UserValid Protos username
P3P-UserMD5 hash of the user's password
Request Parameters
KeyValue
course_idUnique number identifying the course
tournamenttrue | false
teeboxTeebox name
designationM | F
hole_1Score for hole 1
hole_2Score for hole 2
hole_3Score for hole 3
hole_4Score for hole 4
hole_5Score for hole 5
hole_6Score for hole 6
hole_7Score for hole 7
hole_8Score for hole 8
hole_9Score for hole 9
hole_10Score for hole 10
hole_11Score for hole 11
hole_12Score for hole 12
hole_13Score for hole 13
hole_14Score for hole 14
hole_15Score for hole 15
hole_16Score for hole 16
hole_17Score for hole 17
hole_18Score for hole 18
Response XML Payload

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>.