API Reference

Last updated: Thu, 20 Nov 2014 12:21:48 +0000

Match Statistics

Statistical information about a Match or Game

Attributes

Name Type Description Example
name string The name of the statistic "Serving wins"
opponentOneStat string The first opponent's statistical value; can be anything from a number to a time period to a string "7"
opponentTwoStat string The second opponent's statistical value; can be anything from a number to a time period to a string "4"

Match Statistics Current Info (Not Implemented)

A convenience endpoint that return the most current statistics for a given match. If the Match State is IN PROGRESS, the statistics will be for the current game. If the State is COMPLTETE the statistics will be for the Match as a whole. To get full stats, use the /match-stats/ endpoint instead.

GET /match-stats/current/

Required Parameters

Name Type Description Example
matchId integer The unique identifier for a Match 123498

Curl Example

$ curl -n -X GET http://api.ittf.com/1//match-stats/current/
 -G \
  -d matchId=123498

Response Example

HTTP/1.1 200 OK

{
  "meta": {
    "refreshInterval": 15000
  },
  "data": {
    "stats": [
      {
        "name": "Serving wins",
        "opponentOneStat": "7",
        "opponentTwoStat": "4"
      }
    ],
    "duration": "00:04:12",
    "gameNumber": 1,
    "opponentOne": {
      "name": "ZHANG Zoo"
    },
    "opponentTwo": {
      "name": "BOLL Timo"
    }
  }
}

Match Statistics List (Not Implemented)

Statistics for a given match or game.

GET /match-stats/

Required Parameters

Name Type Description Example
matchId integer The unique identifier for a Match 123498

Optional Parameters

Name Type Description Example
gameNumber integer The number that identifies the sequence of this game within a match 1

Curl Example

$ curl -n -X GET http://api.ittf.com/1//match-stats/
 -G \
  -d matchId=123498 \
  -d gameNumber=1

Response Example

HTTP/1.1 200 OK

{
  "meta": {
    "refreshInterval": 15000
  },
  "data": {
    "matchStats": [
      {
        "stats": [
          {
            "name": "Serving wins",
            "opponentOneStat": "7",
            "opponentTwoStat": "4"
          }
        ],
        "duration": "00:04:12",
        "gameNumber": 1,
        "opponentOne": {
          "name": "ZHANG Zoo"
        },
        "opponentTwo": {
          "name": "BOLL Timo"
        }
      }
    ]
  }
}

Match

A Match is a Contest that consists of a sequence of Games between two Opponents

Attributes

Name Type Description Example
id integer The unique identifier for a Match 123498
seriesId nullable integer The ID of the Series to which this match belongs; null when match is not part of a series 3548912
state string The state of the match. Can be UNASSIGNED; meaning no players have been assigned to this match yet, 'UPCOMING'; meaning the Match has yet to start, 'IN PROGRESS, or 'COMPLETE'
one of:"UNASSIGNED" or "UPCOMING" or "IN PROGRESS" or "COMPLETE"		 "COMPLETE"
opponentOne nullable object The first opponent. In cases where the match is unassigned, this field is null. null
opponentOne:name string A nickname for this Opponent "ZHANG Zoo"
opponentOne:score integer The number of points this Opponent has scored 9
opponentOne:position integer The opponents current position within the Event 15
opponentOne:hasWon boolean Indicates wether or not this Opponent has won the Game, Match or Series. Omitted when false true
opponentOne:players nullable array The Players that make up this Opponent. Value is 'null' unless specifically requested via include=['players']. null
opponentOne:players nullable array The Players that make up this Opponent. Value is 'null' unless specifically requested via include=['players']. null
opponentOne:association:id string A unique three-letter identifier for this association "EGY"
opponentOne:association:name string The name of this association, usually a country, but not always "Egypt"
opponentTwo nullable object The second opponent. In cases where this match is unassigned and in cases where the first opponent has received a Bye, this field is null. null
opponentTwo:name string A nickname for this Opponent "ZHANG Zoo"
opponentTwo:score integer The number of points this Opponent has scored 9
opponentTwo:position integer The opponents current position within the Event 15
opponentTwo:hasWon boolean Indicates wether or not this Opponent has won the Game, Match or Series. Omitted when false true
opponentTwo:players nullable array The Players that make up this Opponent. Value is 'null' unless specifically requested via include=['players']. null
opponentTwo:players nullable array The Players that make up this Opponent. Value is 'null' unless specifically requested via include=['players']. null
opponentTwo:association:id string A unique three-letter identifier for this association "EGY"
opponentTwo:association:name string The name of this association, usually a country, but not always "Egypt"
bestOf integer The number of Games an Opponent must win in order to be declared the winner of this Match 5
startDateTime string The Date and Time the Match is scheduled to start supplied as a string conforming to ISO 8601 "2014-11-15T13:15"
table string The table that the current game is being played on. If all games have concluded this is a record of the last table upon which this Match was contested "Table 3"
roundName string The name of the Round in which this Match was or is being played "Quarter Final"
groupName nullable string The name of the Group in which this Match was or is being played. Null when match is not part of a Group. "Group A"
divisionName nullable string The name of the Division in which this Match was or is being played. Null when match is not part of a Division. "Division 1"
stageName nullable string The name of the Stage in which this Match was or is being played. Null when match is not part of a Stage. "Main Draw"
tournamentId integer The Id of the Tournament in which this Match was or is being played 546978
eventType string The type of Event; usually denotes the plurality, gender and team indicator. "MS"
duration string How long it took for the Match to complete in the form 'HH:MM:SS' "00:04:12"
games array a list of Games that make up this Match. 
[{"number"=>1, "matchId"=>125798, "opponentOne"=>{"name"=>"ZHANG Zoo", "score"=>9, "position"=>15, "hasWon"=>true, "players"=>[{"id"=>19087, "firstName"=>"Xin", "middleName"=>"Zhen", "lastName"=>"Xu", "rankings"=>[{"system"=>"World - Under 21", "rank"=>12}], "avatar"=>"http://ittf.com/stories/pictures/xu_xin_16_11_14.jpg", "images"=>["http://ittf.com/stories/pictures/xu_xin_04_10_14.jpg"], "association"=>{"id"=>"EGY", "name"=>"Egypt"}, "nationality"=>"Chinese", "dateOfBirth"=>"1988-08-18", "category"=>nil, "gender"=>"MALE"}], "association"=>{"id"=>"EGY", "name"=>"Egypt"}}, "opponentTwo"=>{"name"=>"ZHANG Zoo", "score"=>9, "position"=>15, "hasWon"=>true, "players"=>[{"id"=>19087, "firstName"=>"Xin", "middleName"=>"Zhen", "lastName"=>"Xu", "rankings"=>[{"system"=>"World - Under 21", "rank"=>12}], "avatar"=>"http://ittf.com/stories/pictures/xu_xin_16_11_14.jpg", "images"=>["http://ittf.com/stories/pictures/xu_xin_04_10_14.jpg"], "association"=>{"id"=>"EGY", "name"=>"Egypt"}, "nationality"=>"Chinese", "dateOfBirth"=>"1988-08-18", "category"=>nil, "gender"=>"MALE"}], "association"=>{"id"=>"EGY", "name"=>"Egypt"}}, "table"=>"Table 5", "dateTime"=>"2014-11-15T13:15"}]
isBye boolean Indicates that this match only has a single opponent who will automatically move on to the next round false
stats nullable array
default: "null"		 null
stats nullable array
default: "null"		 null

Match List (not implemented)

The Match List endpoint returns a collection of matches along with meta data that specifies the interval in milliseconds at which match data is refreshed. By default, the items of the array represent a subset of the full match object. To get additional details; set the include property on the request.

GET /matches

Optional Parameters

Name Type Description Example
since string An ISO 8601 compliant date and time. If set, only returns matches that were updated since the given datetime "2014-11-16T14:55:03Z"
tournamentId integer The Id of the Tournament in which this Match was or is being played 546978
eventType string The type of Event; usually denotes the plurality, gender and team indicator. "MS"
state string The state of the match. Can be UNASSIGNED; meaning no players have been assigned to this match yet, 'UPCOMING'; meaning the Match has yet to start, 'IN PROGRESS, or 'COMPLETE'
one of:"UNASSIGNED" or "UPCOMING" or "IN PROGRESS" or "COMPLETE"		 "COMPLETE"

Curl Example

$ curl -n -X GET http://api.ittf.com/1//matches
 -G \
  -d since=2014-11-16T14%3A55%3A03Z \
  -d tournamentId=546978 \
  -d eventType=MS \
  -d state=COMPLETE

Response Example

HTTP/1.1 200 OK

{
  "meta": {
    "refreshInterval": 15000
  },
  "data": [
    {
      "id": 123498,
      "seriesId": 3548912,
      "state": "COMPLETE",
      "opponentOne": {
        "name": "ZHANG Zoo",
        "score": 9,
        "position": 15,
        "hasWon": true,
        "association": {
          "id": "EGY",
          "name": "Egypt"
        }
      },
      "opponentTwo": {
        "name": "ZHANG Zoo",
        "score": 9,
        "position": 15,
        "hasWon": true,
        "association": {
          "id": "EGY",
          "name": "Egypt"
        }
      },
      "bestOf": 5,
      "startDateTime": "2014-11-15T13:15",
      "table": "Table 3",
      "roundName": "Quarter Final",
      "groupName": "Group A",
      "divisionName": "Division 1",
      "stageName": "Main Draw",
      "tournamentId": 546978,
      "eventType": "MS",
      "duration": "00:04:12",
      "games": [
        {
          "number": 1,
          "matchId": 125798,
          "opponentOne": {
            "name": "ZHANG Zoo",
            "score": 9,
            "position": 15,
            "hasWon": true,
            "players": [
              {
                "id": 19087,
                "firstName": "Xin",
                "middleName": "Zhen",
                "lastName": "Xu",
                "rankings": [
                  {
                    "system": "World - Under 21",
                    "rank": 12
                  }
                ],
                "avatar": "http://ittf.com/stories/pictures/xu_xin_16_11_14.jpg",
                "images": [
                  "http://ittf.com/stories/pictures/xu_xin_04_10_14.jpg"
                ],
                "association": {
                  "id": "EGY",
                  "name": "Egypt"
                },
                "nationality": "Chinese",
                "dateOfBirth": "1988-08-18",
                "category": null,
                "gender": "MALE"
              }
            ],
            "association": {
              "id": "EGY",
              "name": "Egypt"
            }
          },
          "opponentTwo": {
            "name": "ZHANG Zoo",
            "score": 9,
            "position": 15,
            "hasWon": true,
            "players": [
              {
                "id": 19087,
                "firstName": "Xin",
                "middleName": "Zhen",
                "lastName": "Xu",
                "rankings": [
                  {
                    "system": "World - Under 21",
                    "rank": 12
                  }
                ],
                "avatar": "http://ittf.com/stories/pictures/xu_xin_16_11_14.jpg",
                "images": [
                  "http://ittf.com/stories/pictures/xu_xin_04_10_14.jpg"
                ],
                "association": {
                  "id": "EGY",
                  "name": "Egypt"
                },
                "nationality": "Chinese",
                "dateOfBirth": "1988-08-18",
                "category": null,
                "gender": "MALE"
              }
            ],
            "association": {
              "id": "EGY",
              "name": "Egypt"
            }
          },
          "table": "Table 5",
          "dateTime": "2014-11-15T13:15"
        }
      ],
      "isBye": false
    }
  ]
}