Changelog

All notable changes to the WPPR API will be documented here.

[1.1.1] - 2025-12-04

Added

Contextual Player Search

Endpoint: GET /v1/players/search/contextual

A new endpoint that helps you find players by name with contextual information about whether they have played at a specific club or in tournaments organized by a specific company.

Use Case: Instead of searching for a player by only their name, if you provide an organizer company that organized a tournament for this player before, or a club where they played, this endpoint will help you find the right player you are looking for—even if you pass only the player's first name or last name.

Query Parameters:

Parameter	Type	Required	Description
`name`	string	Yes	Player name to search (min 2 chars, supports fuzzy matching)
`organizer_id`	UUID	Conditional	Organizer company ID
`club_id`	UUID	Conditional	Club ID

Note: At least one of organizer_id or club_id must be provided. When both are provided, only players who have played matches in BOTH contexts are returned.

Example Request:

GET /v1/players/search/contextual?name=john&organizer_id=550e8400-e29b-41d4-a716-446655440000

Example Response:

[
  {
    "id": "P30C1B",
    "wppr_id": "P30C1B",
    "wppr_profile_url": "https://wecourts.com/wppr/P30C1B",
    "display_name": "John Doe",
    "rating": 3.791,
    "rating_category_name": "C+",
    "rating_status": "AR",
    "nationality": "AE",
    "gender": "M",
    "display_gender": "Male",
    "display_nationality": "Emirati",
    "display_nationality_flag": "🇦🇪",
    "display_location": "Dubai, UAE",
    "display_location_flag": "🇦🇪",
    "display_gender_nationality": "Emirati • M • 🇦🇪",
    "image_url": "https://example.com/image.jpg",
    "context": {
      "matches_with_organizer": 15,
      "matches_at_club": 8,
      "total_context_matches": 23,
      "confidence_score": 0.85
    }
  }
]

Context Fields:

Field	Type	Description
`matches_with_organizer`	number	Count of matches in tournaments by the specified organizer
`matches_at_club`	number	Count of matches at the specified club
`total_context_matches`	number	Sum of organizer + club matches
`confidence_score`	number	Relevance score from 0.0 to 1.0

Limits:

Results are limited to a maximum of 10 players
Results are sorted by confidence_score in descending order

[1.1.0] - 2025-11-27

Breaking Changes

🚨 Pagination Removed from Player Search

Endpoint: GET /v1/players/search/by-name

The page and limit query parameters have been removed. The endpoint now returns all matching results without pagination.

Before:

GET /v1/players/search/by-name?name=john&page=1&limit=20

After:

GET /v1/players/search/by-name?name=john

Migration Steps:

Remove page and limit parameters from your search requests
Handle the full result set in your application
Implement client-side pagination if needed

🚨 Categories Response Schema Changed

Endpoint: GET /v1/categories/list

The color field has been removed and replaced with a description field.

Old Response:

{
  "name": "C+, B-",
  "range": "3.750 - 4.749",
  "category": "Expert",
  "color": "bg-amber-500",
  "min": 3.75,
  "max": 4.749
}

New Response:

{
  "name": "C+",
  "range": "3.750 - 4.249",
  "category": "Expert",
  "description": "Controlled on court, basic tactics",
  "min": 3.75,
  "max": 4.249
}

Migration Steps:

Remove any code that depends on the color field
Implement your own color mapping if needed for UI
Use the new description field for enhanced user experience

Added

Enhanced Error Response Documentation

All endpoints now return standardized, well-documented error responses:

{
  "error": true,
  "message": "Descriptive error message",
  "statusCode": 401
}

Documented HTTP Status Codes:

400 - Bad Request (invalid query parameters)
401 - Unauthorized (missing or invalid API key)
404 - Not Found (player or resource not found)
500 - Internal Server Error
503 - Service Unavailable (upstream service issues)

Benefits:

More predictable error handling
Better debugging with consistent error messages
Improved client-side error handling logic

Phone Number Format Documentation

Endpoint: GET /v1/players/search/by-phone/{phonenumber}

Enhanced documentation for supported phone number formats:

Supported Formats:

971501234567 (standard)
+971501234567 (with plus prefix)
00971501234567 (with 00 prefix)
971-50-123-4567 (with dashes)
971 50 123 4567 (with spaces)

Benefits:

Clearer documentation of accepted formats
Reduces integration errors
Better developer experience

Comprehensive Property Descriptions

All response properties now include detailed descriptions in the OpenAPI specification:

Player Response Properties:

id - "Player WPPR profile ID"
wppr_id - "WPPR profile identifier"
wppr_profile_url - "URL to the player profile on WeCourts"
display_name - "Player display name"
rating - "Current WPPR rating"
rating_category_name - "Rating category name"
rating_status - "Rating status (e.g., AR for Active Rating)"
nationality - "Nationality ISO2 country code"
gender - "Gender code" (enum: ["M", "F"])
And many more...

Benefits:

Self-documenting API responses
Clearer field purposes and formats
Better TypeScript/type generation support

Schema Requirements

All response schemas now explicitly define required fields using the required array.

Example:

{
  "required": ["id", "wppr_id", "wppr_profile_url", "display_name", "rating_status"]
}

Benefits:

Know which fields are always present
Better TypeScript/type generation
More reliable client-side code

Changed

Player Rating Endpoint Description

Endpoint: GET /v1/players/{wppr_id}/rating

Old description: "Retrieves the current rating and ranking information for a player from their WPPR profile."
New description: "Retrieves the current rating and rating status and rating category for a player from their WPPR profile."

This clarifies that the endpoint returns rating, status, and category information (not ranking).

Match Response Documentation

Endpoint: GET /v1/players/{wppr_id}/matches

All nested match properties now have detailed descriptions:

Match Properties:

match_id - "Match ID"
date - "Match date in ISO format"
display_date - "Human-readable match date"

Team Properties:

team_1 / team_2 - "First team" / "Second team"
won - "Whether this team won the match"
set_1 / set_2 / set_3 - Score information with nullable indicators

Benefits:

Better understanding of complex match data structure
Easier to build match display UI
Clear indication of nullable fields

[1.0.0] - 2025-11-11

Added

Players API

GET /v1/players/:wppr_id - Get player information
GET /v1/players/:wppr_id/rating - Get player rating from WPPR profile
GET /v1/players/:wppr_id/matches - Get player match history
GET /v1/players/:wppr_id/stats - Get player statistics

Technical Details

Base URL: https://developers.wecourts.com/api
OpenAPI: 3.0

Version History

Version	Release Date	Status	Notes
1.1.1	2025-12-04	✅ Current	Contextual player search endpoint
1.1.0	2025-11-27	Stable	Enhanced docs, breaking changes
1.0.0	2025-11-11	Deprecated	Initial release

Support

If you have questions or encounter issues:

Email: [email protected]
Support Portal: WeCourts Support

[1.1.1] - 2025-12-04​

Added​

Contextual Player Search​

[1.1.0] - 2025-11-27​

Breaking Changes​

🚨 Pagination Removed from Player Search​

🚨 Categories Response Schema Changed​

Added​

Enhanced Error Response Documentation​

Phone Number Format Documentation​

Comprehensive Property Descriptions​

Schema Requirements​

Changed​

Player Rating Endpoint Description​

Match Response Documentation​

[1.0.0] - 2025-11-11​

Added​

Players API​

Technical Details​

Version History​

Support​

[1.1.1] - 2025-12-04

Added

Contextual Player Search

[1.1.0] - 2025-11-27

Breaking Changes

🚨 Pagination Removed from Player Search

🚨 Categories Response Schema Changed

Added

Enhanced Error Response Documentation

Phone Number Format Documentation

Comprehensive Property Descriptions

Schema Requirements

Changed

Player Rating Endpoint Description

Match Response Documentation

[1.0.0] - 2025-11-11

Added

Players API

Technical Details

Version History

Support