Live Tennis API · Schema

RankingRecord

One ranking record in force at the requested instant. `system` is always explicit and the systems are never collapsed into a single "rank" — they are not comparable. ATP/WTA and the ITF circuits populate rank+points; UTR populates rating and leaves rank/points null, because UTR is a rating and has no rank.

CompanySportsDataReal-TimeTennis

Properties

Name Type Description
player_id integernull Null only on listing rows for players outside our roster — the listing is kept independent of the roster precisely so a top-N has no silent holes. Always present on per-player records for the official
player_name stringnull The name as the ranking publisher printed it — present on listing rows (where `player_id` may be null), absent on per-player records.
system string
tour stringnull
rank integernull Null for UTR. Null for `elo` in per-player mode too — an Elo has no global rank at a past instant until you say which field and which activity window you mean, and the per-player read is given neither
points integernull Null for UTR and for `elo` — both are ratings, and neither has points.
surface string `elo` only, and absent on every other system. Which of the four independent ladders this rating is. A ladder the player has never played is omitted from the response rather than substituted with anoth
matches integernull `elo` only, and absent on every other system. Cumulative matches on THAT ladder at that date — not the player's career total. Every ladder starts at 1500, so this is what tells you whether a rating is
previous_rank integernull The rank at the immediately preceding snapshot week (ATP/WTA only; null when no prior week is held, and always null for ITF/UTR).
rank_movement integernull The circuit's own signed weekly movement (ITF systems only; null elsewhere).
rating numbernull UTR and `elo` only; null elsewhere. For `elo` this is the Elo itself, on our own scale, which is not comparable with Elo published anywhere else.
effective_date stringnull The publication week this record took effect. For records ingested live rather than from the official weekly publication this is bucketed to the observed week, so it can sit up to six days later than
observed_at stringnull
View JSON Schema on GitHub

JSON Schema

livetennisapi-com-ranking-record-schema.json Raw ↑
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/livetennisapi-com/json-schema/livetennisapi-com-ranking-record-schema.json",
  "title": "RankingRecord",
  "description": "One ranking record in force at the requested instant. `system` is always explicit and the systems are never collapsed into a single \"rank\" — they are not comparable. ATP/WTA and the ITF circuits populate rank+points; UTR populates rating and leaves rank/points null, because UTR is a rating and has no rank.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/livetennisapi-com-rankings-api-openapi.yml#/components/schemas/RankingRecord",
  "type": "object",
  "properties": {
    "player_id": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Null only on listing rows for players outside our roster — the listing is kept independent of the roster precisely so a top-N has no silent holes. Always present on per-player records for the official systems and UTR. For `elo` it is also null on rows for the ~62,000 rated people with no roster row — normal, not an error; `player_name` is always populated, and `archive_player` fetches that person directly."
    },
    "player_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "The name as the ranking publisher printed it — present on listing rows (where `player_id` may be null), absent on per-player records."
    },
    "system": {
      "type": "string",
      "enum": [
        "atp",
        "wta",
        "itf_jt",
        "itf_mt",
        "itf_wt",
        "utr",
        "elo",
        "atp_doubles",
        "wta_doubles"
      ]
    },
    "tour": {
      "type": [
        "string",
        "null"
      ]
    },
    "rank": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Null for UTR. Null for `elo` in per-player mode too — an Elo has no global rank at a past instant until you say which field and which activity window you mean, and the per-player read is given neither. In `elo` listing mode it is the position in the qualified field of THAT call."
    },
    "points": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Null for UTR and for `elo` — both are ratings, and neither has points."
    },
    "surface": {
      "type": "string",
      "enum": [
        "overall",
        "hard",
        "clay",
        "grass"
      ],
      "description": "`elo` only, and absent on every other system. Which of the four independent ladders this rating is. A ladder the player has never played is omitted from the response rather than substituted with another."
    },
    "matches": {
      "type": [
        "integer",
        "null"
      ],
      "description": "`elo` only, and absent on every other system. Cumulative matches on THAT ladder at that date — not the player's career total. Every ladder starts at 1500, so this is what tells you whether a rating is an assessment or a cold start, and it is the number `min_matches` filters on."
    },
    "previous_rank": {
      "type": [
        "integer",
        "null"
      ],
      "description": "The rank at the immediately preceding snapshot week (ATP/WTA only; null when no prior week is held, and always null for ITF/UTR)."
    },
    "rank_movement": {
      "type": [
        "integer",
        "null"
      ],
      "description": "The circuit's own signed weekly movement (ITF systems only; null elsewhere)."
    },
    "rating": {
      "type": [
        "number",
        "null"
      ],
      "description": "UTR and `elo` only; null elsewhere. For `elo` this is the Elo itself, on our own scale, which is not comparable with Elo published anywhere else."
    },
    "effective_date": {
      "type": [
        "string",
        "null"
      ],
      "format": "date",
      "description": "The publication week this record took effect. For records ingested live rather than from the official weekly publication this is bucketed to the observed week, so it can sit up to six days later than the moment the value actually took effect; where both exist for one week the official publication is served."
    },
    "observed_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    }
  }
}

Work with this as data

Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for schemas

4 MCP tools reach this
  • find_json_schemasBrowse and filter every JSON Schema in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/livetennisapi-com-ranking-record"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.