Skip to main content

​
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

​
lat
float
required
Latitude of the venue or location.
​
lng
float
required
Longitude of the venue or location.
​
start_time
string
required
Start time of the booking in ISO 8601 format (UTC). Example: 2026-04-24T18:30:00Z
​
duration_minutes
integer
required
Length of the session in minutes. For example: 60, 90, 120.
​
sport
string
Activity type. Defaults to outdoor if not provided. See supported sports for all valid values.

​
Example request

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'

​
Response

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

​
playability_score
integer
A score from 0–100 indicating how suitable conditions are. Higher is better. See the scoring guide for how this is calculated.
​
recommendation
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
​
rain_risk
string
Rain risk level: low, medium, or high.
​
wind_risk
string
Wind risk level: low, medium, or high.
​
temp_c
float
Expected temperature in Celsius at the start of the session.
​
summary
string
A human-readable summary suitable for displaying directly to your end users.
​
forecast_at
string
ISO 8601 timestamp of when this forecast was generated (UTC).

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