Versions Compared

Old Version 15

changes.mady.by.user Jonathan Cohen

Saved on

compared with

New Version Current

changes.mady.by.user Jonathan Cohen

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Page Tree Search

Overview

You can lookup a USTA player profile given a USTA uaid. Player profiles contain indentifying fields and ratings.

Tne player profile should be called on demand rather than storing the profile within your apdplication. Data within the profile changes frequently and can become stale quickly.

Note

Player profiles contributed from 3rd Parties will not be visible via API unless the player has claimed their account on usta.com.

Info

WTN tennisNumbers are published on Wed am UTC as reflected by the ratingDate field. Only the most recently recorded WTN will be returned for each play type. WTNs corresponding to Singles and Doubles could correspond to different ratingDates if the player has not recorded play activity.

API

This API is called once per player.

URI

Code Block
https://services.usta.com/v1/dataexchange/profile/search?limit=1

Body

Code Block
{
   "selection":{
      "uaid":"2006874790"
   },
   "output":{
      "ratings":true,
      "wtn":true
   }
}

Response

One customer profile is returned per call.

Code Block
{
    "data": [
        {
            "name": "Adelle Parant",
            "uaid": "2006812345",
            "isPrimaryResidenceDeclaration": "N",
            "city": "Tarzana",
            "section": {
                "code": "65",
                "name": "Southern California"
            },
            "district": {
                "code": "17",
                "name": "Southern California",
                "sectionCode": "65"
            },
            "state": "CA",
            "zipcode": "91356-3105",
            "gender": "FEMALE",
            "ageCategory": "ADULT",
            "subscription": {
                "membershipStatus": "ACTIVE",
                "expiryDate": "2023-03-31T23:59:59-0400"
            },
            "wheelchair": false,
            "ratings": {
                "ntrp": {
                    "ntrpRating": 3.5,
                    "ratingType": "C",
                    "ratingDate": "2021-12-31T00:00:00",
                    "ratingExpiration": "2024-12-31T00:00:00",
                    "updatedAt": "2021-12-31T00:00:00",
                    "ratingYear": 2021
                },
                "ballColorRating": null,
                "competitionLevelBallColor": null,
                "wtn": [
                    {
                        "type": "SINGLE",
                        "tennisNumber": 21.56,
                        "confidence": 10,
                        "ratingDate": "2022-07-06",
                        "gameZoneUpper": 19.53,
                        "gameZoneLower": 23.6,
                        "source": "SEED",
                        "lastPlayed": "2018-06-03",
                        "uaid": "2006874790",
                        "tennisId": "PAR9979473",
                        "updatedAt": "2022-07-06T09:39:24",
                        "proZone": false
                    },
                    {
                        "type": "DOUBLE",                    
                        "tennisNumber": 23.65,
                        "confidence": 100,
                        "ratingDate": "2022-07-06",
                        "gameZoneUpper": 21.9,
                        "gameZoneLower": 25.39,
                        "source": "MATCHUPS",
                        "lastPlayed": "2022-06-21",
                        "uaid": "2006874790",
                        "tennisId": "PAR9979473",
                        "updatedAt": "2022-07-06T09:39:24",
                        "proZone": false
                    }
                ]
            },
            "itfTennisId": "PAX9979123"
        }
    ]
}

Handling WTN In The Client Application

There are some key points to note about display of WTNs. When a tennisNumber is calculated, there is a confidence level assigned to it indicating low/medium/high confidence. There are many factors that go into the confidence rating such as frequency of play and how recently the player has recorded a score.

Info

Each WTN is distributed with a confidence level indicating low/medium/high confidence that the tennisNumber reflects the current level of player.

Confidence Level

Confidence levels are recorded in increments of 10 and bucketed into low/medium/high categories. Each application needs to decide how to indicate whether a tennisNumber is supported by confidence level or not.

Level

Number

Low

10, 20, 30

Medium

40, 50, 60

High

70, 80, 90, 100

ITF TennisId

TennisId is the unique identifier for a player within ITF. UAID is the unique identifier within USTA. Client applications can choose to display tennisId and deep link into ITF’s public website http://internationaltennisnumber.com which shows additional information about a player. There are no credentials required to access the ITF website. It is open to all.

Example: https://worldtennisnumber.com/eng/player-profile?id=6127768d9a88a03bfb1ac01d


Sample Curl

You must first retrieve an access token using Bound or Unbound method. See Cognito Client Integration Guide for more on how to request a token.

The following is a sample curl to retrieve a player profile.

Where:

--header 'Authorization: Bearer eyJraW...

specifies the token that you retrieved using the https://stage-account.usta.com/oauth2/tokenendpoint.

Code Block
curl --location --request POST 'https://services.usta.com/v1/dataexchange/profile/search?limit=1' \
--header 'Authorization: Bearer eyJraW...
--header 'Content-Type: application/json' \
--data-raw '{
   "selection":{
      "uaid":"20068747490"
   },
   "output":{
      "ratings":true,
      "wtn":true
   }
}'

Panel
bgColor#FFFFFF

On This Page:

Table of Contents
Panel
bgColor#FFFFFF

More Reading:

https://worldtennisnumber.com/

Quick Reference: World Tennis Number