> ## 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.

# Safe slots

> Rank a list of available booking slots by weather suitability.

## Overview

Pass a list of available time slots — SkyMatch returns them ranked from best to worst weather conditions. Ideal for surfacing the top recommended times in your booking calendar.

```
GET /v1/safe-slots
```

## Query parameters

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

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

<ParamField query="slots" type="string" required>
  Comma-separated list of ISO 8601 start times to evaluate. Maximum 20 slots per request.

  Example: `2026-04-24T10:00:00Z,2026-04-24T12:00:00Z,2026-04-24T18:30:00Z`
</ParamField>

<ParamField query="duration_minutes" type="integer">
  Session length in minutes. Applied to all slots. Defaults to `60`.
</ParamField>

<ParamField query="sport" type="string">
  Activity type. Defaults to `outdoor`. See [supported sports](/supported-sports).
</ParamField>

## Example request

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

  ```javascript Node.js theme={null}
  const slots = [
    '2026-04-24T10:00:00Z',
    '2026-04-24T14:00:00Z',
    '2026-04-24T18:30:00Z'
  ].join(',');

  const params = new URLSearchParams({
    lat: 51.5074,
    lng: -0.1278,
    slots,
    duration_minutes: 90,
    sport: 'padel'
  });

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

  const data = await response.json();
  // data.slots[0] is the best slot
  ```

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

  slots = ','.join([
    '2026-04-24T10:00:00Z',
    '2026-04-24T14:00:00Z',
    '2026-04-24T18:30:00Z'
  ])

  response = requests.get(
    'https://api.skymatch.uk/v1/safe-slots',
    params={
      'lat': 51.5074,
      'lng': -0.1278,
      'slots': slots,
      'duration_minutes': 90,
      'sport': 'padel'
    },
    headers={'X-API-Key': os.environ['SKYMATCH_API_KEY']}
  )
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "slots": [
    {
      "start_time": "2026-04-24T10:00:00Z",
      "playability_score": 91,
      "recommendation": "safe_to_book",
      "rain_risk": "low",
      "wind_risk": "low",
      "rank": 1
    },
    {
      "start_time": "2026-04-24T14:00:00Z",
      "playability_score": 78,
      "recommendation": "proceed_with_caution",
      "rain_risk": "medium",
      "wind_risk": "low",
      "rank": 2
    },
    {
      "start_time": "2026-04-24T18:30:00Z",
      "playability_score": 44,
      "recommendation": "not_recommended",
      "rain_risk": "high",
      "wind_risk": "medium",
      "rank": 3
    }
  ]
}
```

## Response fields

<ResponseField name="slots" type="array">
  Array of evaluated slots, sorted by `playability_score` descending (best first). Each item includes:

  * `start_time` — The original slot time passed in
  * `playability_score` — Suitability score from 0–100
  * `recommendation` — `safe_to_book`, `proceed_with_caution`, or `not_recommended`
  * `rain_risk` — `low`, `medium`, or `high`
  * `wind_risk` — `low`, `medium`, or `high`
  * `rank` — Position in the ranking (1 = best conditions)
</ResponseField>

## Use case: "best time to play" feature

Use this endpoint to add a **Best time to play** suggestion to your booking flow:

1. When a user opens a date, send all available slots for that day to `/safe-slots`
2. Take `slots[0]` (rank 1) and highlight it with a ⭐ badge
3. Show the rest of the calendar normally

This feature alone can meaningfully reduce cancellation rates by nudging users toward better-weather slots at the point of booking.