Safe slots

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

float

required

Latitude of the venue.

float

required

Longitude of the venue.

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

integer

Session length in minutes. Applied to all slots. Defaults to 60.

string

Activity type. Defaults to outdoor. See supported sports.

Example request

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'

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

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']}
)

Response

{
  "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

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)

Use case: “best time to play” feature

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

When a user opens a date, send all available slots for that day to /safe-slots
Take slots[0] (rank 1) and highlight it with a ⭐ badge
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.

Getting started

API Endpoints

Reference

Overview

Query parameters

Example request

Response

Response fields

Use case: “best time to play” feature

​Overview

​Query parameters

​Example request

​Response

​Response fields

​Use case: “best time to play” feature

Overview

Query parameters

Example request

Response

Response fields

Use case: “best time to play” feature