Skip to main content

​
Overview

Returns hour-by-hour weather data including a playability score for each hour. Useful for building weather previews, condition timelines, or calendar heat maps in your booking UI. 
GET /v1/forecast

​
Query parameters

​
lat
float
required
Latitude of the location.
​
lng
float
required
Longitude of the location.
​
days
integer
Number of days to return. Must be between 1 and 7. Defaults to 3.
​
sport
string
Activity type used to weight the per-hour playability scores. Defaults to outdoor. See supported sports.

​
Example request

curl 'https://api.skymatch.uk/v1/forecast
  ?lat=51.5074&lng=-0.1278&days=3&sport=padel' \
  -H 'X-API-Key: your_api_key_here'

​
Response

{
  "location": {
    "lat": 51.5074,
    "lng": -0.1278
  },
  "hours": [
    {
      "time": "2026-04-24T06:00:00Z",
      "temp_c": 12.1,
      "rain_mm": 0.0,
      "wind_kmh": 9,
      "cloud_cover_pct": 15,
      "playability_score": 94
    },
    {
      "time": "2026-04-24T07:00:00Z",
      "temp_c": 13.0,
      "rain_mm": 0.0,
      "wind_kmh": 11,
      "cloud_cover_pct": 20,
      "playability_score": 92
    },
    {
      "time": "2026-04-24T18:00:00Z",
      "temp_c": 17.4,
      "rain_mm": 0.1,
      "wind_kmh": 14,
      "cloud_cover_pct": 32,
      "playability_score": 86
    }
  ]
}

​
Response fields

​
location
object
The coordinates used for the forecast.
​
hours
array
Array of hourly forecast objects, each containing:
  • time — ISO 8601 timestamp for this hour (UTC)
  • temp_c — Temperature in Celsius
  • rain_mm — Rainfall in millimetres expected during this hour
  • wind_kmh — Average wind speed in km/h
  • cloud_cover_pct — Cloud cover as a percentage (0–100)
  • playability_score — Weather suitability score for this hour (0–100)

​
Use case: calendar heat map

A common pattern is to fetch 7 days of forecast data when a user opens your booking calendar, then colour-code each available slot by its playability_score:
  • 🟢 80–100 — highlight as recommended
  • 🟡 50–79 — show as marginal
  • 🔴 0–49 — dim or flag as risky
This helps users naturally gravitate toward lower-cancellation slots without you needing to say anything.