Quick Reference: RankList Catalog

Endpoint: POST {Host}/v1/dataexchange/rankings/list/catalog HTTP/1.1

Description:
Retrieves a list of supported USTA ranklists and the associated division meta-data to use in subsequent queries. The concept of a ranking list has been broken down into its constituent fields which are returned by the API. Subsequent calls to the Ranking Query endpoint must include all of the fields returned by the catalog api.

For informational purposes, please see below the metadata and possible values returned by the API. (Please note, the API may return null values where appropriate)

Fields that identify a Division

Fields that identify a Division
playerType	ADULT, JUNIOR, WHEELCHAIR, FAMILY
rankListGender	M, F, X, C	M = Male, F = Female, X = Mixed, C = Coed
playerLevel	Op, L3_0, L3_5, L4_0, L4_5, L5_0, SS, A, B, C, D, QUAD	NTRP and Wheelchair values
ageRestriction	y12, y14, y16, y18, y30, y35, y40, y45, y50, y55, y60, y65, y70, y75, y80, y85, y90, y95
ageRestrictionModifier	UNDER, OVER	Must be used with ageRestriction
matchFormat	SINGLES, DOUBLES
matchFormatType	INDIVIDUAL, TEAM
familyCategory	null	TBD
listType	STANDING, SEEDING, YEAR_END, BONUS_POINTS, QUOTA

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: Retrieve the catalog for Girls' 14 National Standings List (combined)

POST /v1/dataexchange/rankings/list/catalog HTTP/1.1
Host: stage-services.usta.com
Authorization: Bearer eyJraWQiOiI1d.....oorRetRBuhYTXA  (Token Shortened for example clarity)
Content-Type: application/json
{
    "selection": {
        "playerType": "JUNIOR",
        "rankListGender": "F",
        "ageRestriction": "y14",
        "ageRestrictionModifier": "Under",
        "listType": "Standing"
    }
}

All selection criteria attributes are optional. If passed API will return the filtered list.

Sample API Return

{
    "ranklists": [
        {
            "catalogId": "JUNIOR_NULL_F_STANDING_Y14_UNDER_NULL_NULL_NULL",
            "listType": "STANDING",
            "playerType": "JUNIOR",
            "playerLevel": null,
            "rankListGender": "F",
            "ageRestriction": "y14",
            "ageRestrictionModifier": "UNDER",
            "matchFormat": null,
            "matchFormatType": null,
            "description": "Girls' 14 National Standings List (combined)",
            "familyCategory": null
        }
    ]
}

Sample Postman Collection

Please include here