Match Play Ratings
Match Play Ratings (MP Ratings) are player ratings based on head-to-head results between players. It does not concern itself with results from best game/herb tournaments, pingolf tournaments, selfie leagues or any other tournament formats where direct play is not included. While main tournament results cannot be included, results from any playoffs or finals that include direct play is eligible for inclusion. E.g. if a best game tournament includes a PAPA style finals bracket, results from the bracket are eligible.

These ratings are meant as a supplement to the IFPA world pinball rankings. Match Play will be working with IFPA to submit MP Ratings to IFPA as input to their WPPR formula, hopefully starting in 2018.

In order to provide accurate ratings, it’s imperative that MP Ratings includes results from a wide range of tournaments. This document describes how third-party tournament software can expose and submit results data for inclusion in MP Ratings.

MP Ratings is based on the Glicko algorithm.
MP Ratings is available at https://matchplay.events/live/ratings 

Third-party result submissions

The overall flow for submitting results from a third-party app is:

  • Third-party exposes a JSON document with results data
  • Third-party presents the tournament director with a link or button to the MP Ratings submission site. This link includes a reference to the JSON document
  • Tournament director clicks link and is taken to MP Ratings
  • Tournament director logs in to their Match Play Events user account
  • MP Ratings downloads the JSON document and validates the domain and data format
  • If successful the tournament organizer is shown a confirmation screen with disambiguated players and a confirm button
  • If not an error screen with a link back to the third-party app is shown
  • Upon confirmation MP Ratings will place the results in the queue for processing
  • Tournament organizer is shown a success screen with a link back to the third-party app

As you can see the minimum effort needed for a third-party app is to expose a JSON document and place a link in the app.

Submission deadlines & correcting errors

The Glicko algorithm depends on results being processed in the correct order. MP Ratings are calculated daily but it’s not always possible to tournament organizers to submit results immediately upon tournament completion. For that reason MP Ratings are calculated with a seven-day delay.

Tournament results that are not submitted within seven days of the completion date will not be included in the ratings until the ratings are recalculated from scratch (currently happening on an irregular schedule). Submitting incorrect completion dates may result in the tournament organizer or the third-party being prohibited from submitting future results.

The tournament organizer can correct any mistakes by resubmitting the results.

Submission URL

The submission URL should be of the format: https://matchplay.events/live/ratings/submissions?data_url=[JSON_DOCUMENT_URL] where [JSON_DOCUMENT_URL] is the URL of the JSON document containing tournament data.

JSON document format

The JSON document must contain the following values:

  • dev — Optional boolean flag. Setting to true will let third-party validate their JSON documents without submitting results for the rating system
  • external_name - Short string identifying the third-party app
  • external_id - ID identifying the tournament uniquely for the third-party app (e.g. the internal database ID). String or integer
  • event_name - Name of tournament or event (e.g. a single league meeting)
  • completed_at - Tournament or event completion datetime as an ISO-8601 string.
  • event_url - Public URL for the tournament
  • players - Array of players in the tournament/event. Details below
  • results - Individual results. Details below

Players section
The players section is a list of players including any relevant id numbers. A player must have a unique external_id (that’s used in the results section) and a name. Other fields (ifpa_id and matchplay_user_id) are optional.

The external_id does not need to be globally unique. It only needs to be unique for the individual submission.

Example: