Player

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/livetennisapi-com/json-schema/livetennisapi-com-player-schema.json",
  "title": "Player",
  "x-generated": "2026-10-28",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/livetennisapi-com-openapi.yaml#/components/schemas/Player",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer"
    },
    "name": {
      "type": "string"
    },
    "tour": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "atp",
        "wta",
        null
      ],
      "description": "The circuit the player is filed under: atp | wta | null (normalised 2026-09-24 — the capitalised and level values no longer appear). Not the competition level (use the match's tier) and not the draw (use the match's draw). A doubles team filed under a circuit of its own carries that circuit; one filed under a level word or nothing falls back to the circuit both its members are filed under, and is null when they disagree or either is unknown. null means not filed, never a guess. Distinct from the match-level tour, whose vocabulary is the tour-group filter's (atp | wta | challenger | itf | juniors)."
    },
    "country": {
      "type": [
        "string",
        "null"
      ]
    },
    "ranking": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Official singles ranking POSITION (the ordinal: 1, 25, 100) — never points, seed, race, UTR, Elo or a doubles rank. Men from the official ATP table, women from the WTA table, chosen by the player (a Challenger or ITF man who holds an ATP ranking carries it here). Refreshed from the standings ahead of each match the player has with us; a player who has not played recently keeps their last refreshed position. `null` when no ranking is held (doubles teams, most ITF/junior-only players). Always the CURRENT record, even on historical matches — use `/rankings?as_of=` for the rank in force on a date."
    },
    "ranking_points": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Points on the same official table, refreshed with `ranking`."
    },
    "ranking_status": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "ranked",
        "unranked",
        "unverified",
        null
      ],
      "description": "What the last reconcile against the published ATP/WTA singles tables found (added 2026-09-23). `ranked` = on the table (`ranking` is that row). `unranked` = the full table was fetched and the player was not on it (a `ranking` here is the last value held, not current). `unverified` = could not be checked (no id, a name mismatch, or never checked). Null on doubles teams."
    },
    "ranking_checked_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When that reconcile ran, UTC (added 2026-09-23)."
    },
    "ranking_movement": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "up",
        "down",
        "same",
        null
      ]
    },
    "itf_ranking": {
      "type": [
        "object",
        "null"
      ],
      "description": "Added 2026-10-12, paid tiers (BASIC, PRO, ULTRA), null on a FREE key. The player's CURRENT rank on the ITF's own published World Tennis Tour ranking — the rank most ITF and junior players hold while they have no ATP/WTA one. `system` names the circuit (`itf_mt` men's pro, `itf_wt` women's pro, `itf_jt` juniors); a player ranked on a pro circuit and the junior one carries the pro rank. `rank_date` is the ITF's publication date of that row (weekly), so a stale rank is visible as such. NOT comparable with `ranking` (a circuit rank 1 is tens of points) and never written into it. Joined by the same exact ITF id `itf_id` exposes at ULTRA, never by name. Null when no ITF link is held, when that id is held by more than one roster row, when no published row exists, and on doubles teams. The weekly history of these ranks stays at `/rankings?system=itf_*` (ULTRA).",
      "properties": {
        "system": {
          "type": "string",
          "enum": [
            "itf_mt",
            "itf_wt",
            "itf_jt"
          ]
        },
        "rank": {
          "type": "integer"
        },
        "points": {
          "type": [
            "number",
            "null"
          ]
        },
        "rank_date": {
          "type": "string",
          "format": "date"
        }
      },
      "required": [
        "system",
        "rank",
        "points",
        "rank_date"
      ]
    },
    "hand": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "R",
        "L",
        null
      ]
    },
    "backhand": {
      "type": [
        "integer",
        "null"
      ],
      "enum": [
        1,
        2,
        null
      ]
    },
    "birthday": {
      "type": [
        "string",
        "null"
      ],
      "format": "date"
    },
    "height_cm": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Added 2026-10-22. Single-player read (`/players/{playerId}`) only; paid tiers (BASIC, PRO, ULTRA), null on a FREE key. Height in centimetres from the results archive's record of the same person. Null when the player has no archive record or the archive holds no height. Never inferred."
    },
    "doubles_ranking": {
      "type": [
        "object",
        "null"
      ],
      "description": "Added 2026-10-22. Single-player read (`/players/{playerId}`) only; paid tiers (BASIC, PRO, ULTRA), null on a FREE key. The current position on the official ATP/WTA doubles table, from our weekly refresh of the published tables. `observed_on` is the UTC date that refresh last found the player on the table. Null when the player is not on the table or the last sighting is more than 21 days old. Never copied into `ranking`, which stays the singles position.",
      "properties": {
        "rank": {
          "type": "integer"
        },
        "points": {
          "type": [
            "integer",
            "null"
          ]
        },
        "observed_on": {
          "type": "string",
          "format": "date"
        }
      }
    },
    "itf_id": {
      "type": [
        "integer",
        "null"
      ],
      "description": "ULTRA only (added 2026-09-24). The player's identifier in the ITF ranking tables we publish under `system=itf_*` — the `itf_jt` / `itf_mt` / `itf_wt` rows of `/rankings` are linked to this player by it (an id join, never a name match). One human's id across singles and doubles rows, so a join key, not a per-row primary key. Null when no ITF link is held and on doubles teams. Absent, not null, below ULTRA."
    },
    "is_doubles_team": {
      "type": "boolean"
    },
    "profile_restated_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When the published PROFILE of this player was LAST corrected (UTC), added 2026-10-05 — the player twin of `result_restated_at`. A correction is a change to a published profile field after it was first published; today that is the name (where the held name was another person's, from 2026-10-06) or the birth date, corrected to the results archive's record of the same person where the two disagreed. Null while the profile stands as first published. Poll `GET /players?restated_since=` to find corrections."
    },
    "profile_version": {
      "type": "integer",
      "description": "1 plus the number of corrections to the published profile (added 2026-10-05), the player twin of `result_version`. 1 = the profile stands as first published. Record it with the profile you hold and compare on re-read — a higher number means a field you hold was superseded."
    },
    "archive_player_id": {
      "type": [
        "integer",
        "null"
      ],
      "description": "The player's person id in the results archive (added 2026-09-23) — the id `/history/archive/players` publishes as `id` and archive match rows carry as `winner.player_id` / `loser.player_id`. Scoped by `tour` (men and women are numbered independently). Set by a tour-scoped link built offline from names and birth dates; null where none exists. Measured 2026-09-23: 35 of 5,914 links (0.6%) pointed at a differently named person; all 35 repaired on 2026-09-24. Confirm with name and birthday where identity matters."
    },
    "data_completeness": {
      "type": "object",
      "description": "How much biographical detail is known for this player, so a consumer can distinguish \"never published\" from \"not yet filled in\" without probing. Present on every player in a match payload. Lower tours carry far less of it than main tour.",
      "properties": {
        "known": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Fields populated, of `of`. NULL on a doubles team, where per-player biography does not apply — distinct from `0`, which means the fields apply and none are known. Do not decode this into a non-nullable integer."
        },
        "of": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Fields considered. NULL on a doubles team, as for `known`."
        },
        "missing": {
          "type": "array",
          "description": "Names of the unpopulated fields, e.g. [\"backhand\", \"hand\"].",
          "items": {
            "type": "string"
          }
        },
        "note": {
          "type": "string",
          "description": "Present only when the object is not applicable, explaining why (e.g. a doubles team)."
        }
      }
    },
    "stats": {
      "type": "object",
      "description": "Single-player endpoint only",
      "properties": {
        "ratings": {
          "type": [
            "object",
            "null"
          ]
        },
        "ratings_as_of": {
          "type": [
            "string",
            "null"
          ],
          "format": "date",
          "description": "The date (UTC) the `ratings` block was last refreshed (added 2026-09-10). The current Elo is refreshed every week from the published rating tables; read this before treating a rating as this week's. Null when there is no rating."
        },
        "season": {
          "type": [
            "array",
            "null"
          ]
        }
      }
    }
  }
}