List match suggestions

GET

/players/{player_id}/match-suggestions

const url = 'https://api.krkplaystennis.example/v1/players/plr_2b7xq9mhk4/match-suggestions?limit=5&max_rating_gap=150&venue_id=ven_7hk2p9wq4m';
const options = {method: 'GET', headers: {'X-API-Key': '<X-API-Key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.krkplaystennis.example/v1/players/plr_2b7xq9mhk4/match-suggestions?limit=5&max_rating_gap=150&venue_id=ven_7hk2p9wq4m' \
  --header 'X-API-Key: <X-API-Key>'

Returns opponents for a player, ranked by how close their rating is. A suggested opponent always shares at least one availability window with the player.

This list isn’t paginated: it returns the best limit suggestions.

Authorizations

ApiKeyAuth

Parameters

Path Parameters

player_id

required

A player ID. Starts with plr_.

string

/^plr_[a-z0-9]{10}$/

The player ID.

Query Parameters

limit

integer

default: 5 >= 1 <= 10

Maximum number of suggestions to return.

max_rating_gap

integer

default: 150 <= 500

Maximum difference between the player’s rating and an opponent’s rating, in either direction.

venue_id

A venue ID. Starts with ven_.

string

/^ven_[a-z0-9]{10}$/

Returns only opponents who list this venue as a preferred venue.

Responses

200

Suggested opponents, closest rating first.

application/json

object

data

required

Array<object>

object

player

required

The suggested opponent.

object

required

A player ID. Starts with plr_.

string

/^plr_[a-z0-9]{10}$/

display_name

required

string

rating

required

A player’s current rating and confidence.

object

value

required

A rating. New players start between 1000 and 1800, based on their self-assessed NTRP level.

integer

confidence

required

How settled a rating is, from 0 to 100. New players start at 20. Each rated match adds 10, up to 95. After 60 days without a rated match, confidence drops by 5 every 30 days, down to 20.

integer

<= 100

rating_gap

required

The absolute difference between the two players’ ratings.

integer

overlapping_availability

required

Weekly time windows when both players are available. Always has at least one item.

Array<object>

>= 1 items

A weekly time window, in local time (Europe/Warsaw).

object

day

required

string

Allowed values: monday tuesday wednesday thursday friday saturday sunday

start

required

Start time, as HH:MM in 24-hour format.

string

/^([01][0-9]|2[0-3]):[0-5][0-9]$/

end

required

End time, as HH:MM in 24-hour format. Must be later than start.

string

/^([01][0-9]|2[0-3]):[0-5][0-9]$/

shared_venue_ids

required

Venues both players prefer. Can be empty.

Array<string>

Examples

suggestions

Suggested opponents for Ola

{
  "data": [
    {
      "player": {
        "id": "plr_8mq4ws1yd6",
        "display_name": "Marta Z.",
        "rating": {
          "value": 1382,
          "confidence": 30
        }
      },
      "rating_gap": 50,
      "overlapping_availability": [
        {
          "day": "tuesday",
          "start": "19:00",
          "end": "21:00"
        }
      ],
      "shared_venue_ids": [
        "ven_7hk2p9wq4m"
      ]
    },
    {
      "player": {
        "id": "plr_9fz3tr6wn1",
        "display_name": "Kasia W.",
        "rating": {
          "value": 1499,
          "confidence": 70
        }
      },
      "rating_gap": 67,
      "overlapping_availability": [
        {
          "day": "saturday",
          "start": "10:00",
          "end": "13:00"
        }
      ],
      "shared_venue_ids": [
        "ven_7hk2p9wq4m"
      ]
    }
  ]
}

400

The request is malformed, for example a query parameter has the wrong type.

application/problem+json

An error, as RFC 9457 problem details.

object

type

required

A URL that identifies the error type and links to its documentation.

string format: uri

title

required

A short summary of the error type. It’s the same for every error of this type.

string

status

required

The HTTP status code.

integer

>= 400 <= 599

detail

required

An explanation of this occurrence of the error.

string

instance

The request path that caused the error.

string

errors

One item per invalid field or parameter. Only for invalid-request, invalid-score, and validation-failed.

Array<object>

object

pointer

required

A JSON Pointer to the invalid field in the request body, or #/ followed by the name of an invalid query parameter.

string

detail

required

What’s wrong with the field and how to fix it.

string

Examples

invalidRequest

Limit out of range

{
  "type": "https://saverio-cirillo.com/krk-plays-tennis-api/errors/#invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "The request has 1 invalid parameter.",
  "instance": "/v1/players",
  "errors": [
    {
      "pointer": "#/limit",
      "detail": "limit must be between 1 and 100."
    }
  ]
}

401

The credentials are missing, invalid, or expired.

application/problem+json

An error, as RFC 9457 problem details.

object

type

required

A URL that identifies the error type and links to its documentation.

string format: uri

title

required

A short summary of the error type. It’s the same for every error of this type.

string

status

required

The HTTP status code.

integer

>= 400 <= 599

detail

required

An explanation of this occurrence of the error.

string

instance

The request path that caused the error.

string

errors

One item per invalid field or parameter. Only for invalid-request, invalid-score, and validation-failed.

Array<object>

object

pointer

required

A JSON Pointer to the invalid field in the request body, or #/ followed by the name of an invalid query parameter.

string

detail

required

What’s wrong with the field and how to fix it.

string

Examples

unauthenticated

Missing API key

{
  "type": "https://saverio-cirillo.com/krk-plays-tennis-api/errors/#unauthenticated",
  "title": "Authentication required",
  "status": 401,
  "detail": "Send a valid API key in the X-API-Key header.",
  "instance": "/v1/players/plr_2b7xq9mhk4"
}

404

No resource exists with this ID.

application/problem+json

An error, as RFC 9457 problem details.

object

type

required

A URL that identifies the error type and links to its documentation.

string format: uri

title

required

A short summary of the error type. It’s the same for every error of this type.

string

status

required

The HTTP status code.

integer

>= 400 <= 599

detail

required

An explanation of this occurrence of the error.

string

instance

The request path that caused the error.

string

errors

One item per invalid field or parameter. Only for invalid-request, invalid-score, and validation-failed.

Array<object>

object

pointer

required

A JSON Pointer to the invalid field in the request body, or #/ followed by the name of an invalid query parameter.

string

detail

required

What’s wrong with the field and how to fix it.

string

Examples

notFound

Unknown player ID

{
  "type": "https://saverio-cirillo.com/krk-plays-tennis-api/errors/#not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No player exists with the ID plr_0000000000.",
  "instance": "/v1/players/plr_0000000000"
}

429

You sent too many requests. Wait for the number of seconds in Retry-After, then retry.

application/problem+json

An error, as RFC 9457 problem details.

object

type

required

A URL that identifies the error type and links to its documentation.

string format: uri

title

required

A short summary of the error type. It’s the same for every error of this type.

string

status

required

The HTTP status code.

integer

>= 400 <= 599

detail

required

An explanation of this occurrence of the error.

string

instance

The request path that caused the error.

string

errors

One item per invalid field or parameter. Only for invalid-request, invalid-score, and validation-failed.

Array<object>

object

pointer

required

A JSON Pointer to the invalid field in the request body, or #/ followed by the name of an invalid query parameter.

string

detail

required

What’s wrong with the field and how to fix it.

string

Examples

rateLimited

Rate limit reached

{
  "type": "https://saverio-cirillo.com/krk-plays-tennis-api/errors/#rate-limited",
  "title": "Rate limit reached",
  "status": 429,
  "detail": "This API key is limited to 60 requests per minute. Retry after 30 seconds.",
  "instance": "/v1/matches"
}

Headers

Retry-After

integer

>= 1

Number of seconds to wait before you retry.