Skip to main content

​
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

​
lat
float
required
Latitude of the venue.
​
lng
float
required
Longitude of the venue.
​
slots
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
​
duration_minutes
integer
Session length in minutes. Applied to all slots. Defaults to 60.
​
sport
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'

​
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

​
slots
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:
  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.