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

Â