> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skymatch.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Booking confidence

> Check whether a booking slot is safe to proceed based on weather conditions.

## Overview

This is the core SkyMatch endpoint. Call it when a user selects a booking slot — pass the location, time, and activity type, and get back a clear recommendation.

```
GET /v1/booking-confidence
```

## Query parameters

<ParamField query="lat" type="float" required>
  Latitude of the venue or location.
</ParamField>

<ParamField query="lng" type="float" required>
  Longitude of the venue or location.
</ParamField>

<ParamField query="start_time" type="string" required>
  Start time of the booking in ISO 8601 format (UTC). Example: `2026-04-24T18:30:00Z`
</ParamField>

<ParamField query="duration_minutes" type="integer" required>
  Length of the session in minutes. For example: `60`, `90`, `120`.
</ParamField>

<ParamField query="sport" type="string">
  Activity type. Defaults to `outdoor` if not provided. See [supported sports](/supported-sports) for all valid values.
</ParamField>

## Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl 'https://api.skymatch.uk/v1/booking-confidence
    ?lat=51.5074&lng=-0.1278
    &start_time=2026-04-24T18:30:00Z
    &duration_minutes=90
    &sport=padel' \
    -H 'X-API-Key: your_api_key_here'
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({
    lat: 51.5074,
    lng: -0.1278,
    start_time: '2026-04-24T18:30:00Z',
    duration_minutes: 90,
    sport: 'padel'
  });

  const response = await fetch(
    `https://api.skymatch.uk/v1/booking-confidence?${params}`,
    { headers: { 'X-API-Key': process.env.SKYMATCH_API_KEY } }
  );

  const data = await response.json();
  console.log(data.recommendation); // "safe_to_book"
  ```

  ```python Python theme={null}
  import requests, os

  response = requests.get(
    'https://api.skymatch.uk/v1/booking-confidence',
    params={
      'lat': 51.5074,
      'lng': -0.1278,
      'start_time': '2026-04-24T18:30:00Z',
      'duration_minutes': 90,
      'sport': 'padel'
    },
    headers={'X-API-Key': os.environ['SKYMATCH_API_KEY']}
  )

  data = response.json()
  print(data['recommendation'])  # safe_to_book
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "playability_score": 86,
  "recommendation": "safe_to_book",
  "rain_risk": "low",
  "wind_risk": "low",
  "temp_c": 17.4,
  "summary": "Good conditions for outdoor padel.",
  "forecast_at": "2026-04-24T18:00:00Z"
}
```

## Response fields

<ResponseField name="playability_score" type="integer">
  A score from 0–100 indicating how suitable conditions are. Higher is better. See the [scoring guide](/scoring) for how this is calculated.
</ResponseField>

<ResponseField name="recommendation" type="string">
  One of three values:

  * `safe_to_book` — score is 80 or above, conditions look good
  * `proceed_with_caution` — score is 50–79, conditions are marginal
  * `not_recommended` — score is below 50, high cancellation risk
</ResponseField>

<ResponseField name="rain_risk" type="string">
  Rain risk level: `low`, `medium`, or `high`.
</ResponseField>

<ResponseField name="wind_risk" type="string">
  Wind risk level: `low`, `medium`, or `high`.
</ResponseField>

<ResponseField name="temp_c" type="float">
  Expected temperature in Celsius at the start of the session.
</ResponseField>

<ResponseField name="summary" type="string">
  A human-readable summary suitable for displaying directly to your end users.
</ResponseField>

<ResponseField name="forecast_at" type="string">
  ISO 8601 timestamp of when this forecast was generated (UTC).
</ResponseField>

## Showing results to users

The `summary` field is designed to be shown directly in your UI. For example:

> ⭐ **Recommended** — Good conditions for outdoor padel.

Or for a caution case:

> ⚠️ **Marginal conditions** — Light rain possible. Consider an indoor backup.

You can also use `playability_score` to drive a visual indicator like a colour-coded badge or progress bar.