Quick Reference: RankList Query

Endpoint: POST {Host}/v1/dataexchange/rankings/list

Description:
Retrieve a published USTA rank list using division meta-data from the DEX Ranklist Catalog endpoint. The Ranklist API endpoint should be called first on order to get the proper meta-data to pass to the endpoint.

Rankings data is updated on a 15 minute interval. Newly published ranking lists will take 15 minutes to appear.
In order to search for a rank list, the constituent parts of the lookup criteria must be provided.
The uaids Object is used to look up a list of up to 128 UAIDs in a single request. More than 128 UAID's need multiple calls by the caller. (optional)
If asOfDate segment data is not passed, API will return the latest published list.
The asOfDate object which is used to retrieve lists for a specific publish date can be included in the request to return ranklists that are "before", "after" or "equal" to a publishDate.
If catalogId is passed return results corresponding to catalogId and publish date. Ignore all other selection criteria even if supplied. (optional)
if no publish date is passed with catalogId, the latest published results will be returned.

Authentication: Bearer Token

USTA will issue a Client Key / Secret for each partner with an included security scope. Calls can be made to https://stage-account.usta.com/oauth2/token to obtain a bearer token using OAuth2 client credentials.

Sample API Request

Example:

POST /v1/dataexchange/rankings/list HTTP/1.1
Host: stage-services.usta.com
Authorization: Bearer eyJraWQiO...AAui1o6N8w
Content-Type: application/json

{
   "selection" : {
        "playerType": "JUNIOR",
        "playerLevel": null,
        "ageRestriction": "y14",
        "ageRestrictionModifier": "UNDER",
        "rankListGender": "M",
        "listType": "standing"
   }, "asOfDate": {
            "publishDate": "2021-01-21",
            "modifier": "after"
        },
    "filters": {
        "uaids": [
            "2010641597",
            "2010747389"
        ]
    }
}

Sample API Return

{
    "playerType": "JUNIOR",
    "playerLevel": null,
    "ageRestriction": "y14",
    "ageRestrictionModifier": "UNDER",
    "rankListGender": "M",
    "listType": "STANDING",
    "matchFormat": null,
    "matchFormatType": null,
    "publishDate": "2021-04-27T15:24:23.959Z",
    "createdAt": "2021-04-27T15:24:26.217Z",
    "updatedAt": "2021-04-27T15:28:54.655Z",
    "catalogId": "JUNIOR_NULL_M_STANDING_Y14_UNDER_NULL_NULL_NULL",
    "displayLabel": "Boys' 14 National Standings List (combined)",
    "totalCount": 2,
    "rankings": [
        {
            "participants": [
                {
                    "uaid": "2010641597",
                    "name": "Daniel Greene",
                    "city": "Dover",
                    "state": "MA",
                    "section": "New England",
                    "district": "Eastern Massachusetts"
                }
            ],
            "rank": 1,
            "record": {
                "win": 5,
                "loss": 0
            },
            "points": 1159,
            "pointsRecord": {
                "singlesPoints": 900,
                "doublesPoints": 0,
                "bonusPoints": 259
            },
            "trendDirection": "no change"
        },
        {
            "participants": [
                {
                    "uaid": "2010747389",
                    "name": "Jonah Chernett",
                    "city": "Bloomfield Hills",
                    "state": "MI",
                    "section": "Midwest",
                    "district": "S.E. Michigan"
                }
            ],
            "rank": 3,
            "record": {
                "win": 6,
                "loss": 0
            },
            "points": 788,
            "pointsRecord": {
                "singlesPoints": 540,
                "doublesPoints": 0,
                "bonusPoints": 248
            },
            "trendDirection": "no change"
        }
    ]
}

Sample Postman Collection

Please include here