Hourly forecast

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

float

required

Latitude of the location.

float

required

Longitude of the location.

integer

Number of days to return. Must be between 1 and 7. Defaults to 3.

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'

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

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

const data = await response.json();

import requests, os

response = requests.get(
  'https://api.skymatch.uk/v1/forecast',
  params={ 'lat': 51.5074, 'lng': -0.1278, 'days': 3, 'sport': 'padel' },
  headers={'X-API-Key': os.environ['SKYMATCH_API_KEY']}
)

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

object

The coordinates used for the forecast.

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.

Getting started

API Endpoints

Reference

Overview

Query parameters

Example request

Response

Response fields

Use case: calendar heat map

​Overview

​Query parameters

​Example request

​Response

​Response fields

​Use case: calendar heat map

Overview

Query parameters

Example request

Response

Response fields

Use case: calendar heat map