Players

GET /v1/players/{username}

Plan: Included on Starter, Pro, and Enterprise.

Returns profile fields and computed rating. Public profiles are readable by any partner. Private profiles are readable if your partner created them or they sit on one of your rosters — otherwise 404.

curl -s "https://api.padelrank.me/v1/players/maria_s" \
    -H "Authorization: Bearer $PADELRANK_API_KEY"

Example response shape:

{
  "id": "uuid",
  "username": "maria_s",
  "display_name": "Maria Silva",
  "country_code": "PT",
  "rating": {
    "padelrank_score": 2840,
    "confidence_level": "established",
    "confidence_label": "Medium confidence",
    "matches_played": 22
  }
}

GET /v1/players/search

Prefix search on public usernames. Query params: q (min 2 chars), limit (max 50).

curl -s "https://api.padelrank.me/v1/players/search?q=mar&limit=10" \
  -H "Authorization: Bearer $PADELRANK_API_KEY"

GET /v1/players/{username}/matches

Completed match history with set scores and optional game order. Scope: read:players. See Coach analysis.

curl -s "https://api.padelrank.me/v1/players/maria_s/matches?limit=20" \
    -H "Authorization: Bearer $PADELRANK_API_KEY"

GET /v1/players/{username}/analysis

Plan: Requires Pro or Enterprise. Starter receives HTTP 403 plan_forbidden.

Aggregated scoreboard patterns for coaches. Scope: read:intelligence.

curl -s "https://api.padelrank.me/v1/players/maria_s/analysis?limit=50" \
    -H "Authorization: Bearer $PADELRANK_API_KEY"

GET /v1/players/{username}/progress

Score history for the player card / parent update. Scope: read:players.

curl -s "https://api.padelrank.me/v1/players/maria_s/progress" \
    -H "Authorization: Bearer $PADELRANK_API_KEY"

GET /v1/players/{username}/card

One payload for a club app: rating, 7/30/90-day windows, form, consistency, headline coaching insight, and the last five matches. Scope: read:players.

curl -s "https://api.padelrank.me/v1/players/maria_s/card" \
    -H "Authorization: Bearer $PADELRANK_API_KEY"

POST /v1/players

Plan: Requires Pro or Enterprise. Starter receives HTTP 403 plan_forbidden.

Idempotent registration by username. Scope: write:players. Clubs should set profile_is_public: false for amateurs. Optional roster_slug adds them to a group in the same call (and defaults the profile to private when you omit profile_is_public).

curl -s -X POST "https://api.padelrank.me/v1/players" \
  -H "Authorization: Bearer $PADELRANK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "maria_s",
    "display_name": "Maria Silva",
    "country_code": "PT",
    "profile_is_public": false,
    "roster_slug": "weeknight-amateurs"
  }'