> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skymatch.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Hourly forecast

> Get a detailed hourly weather breakdown for a location over the next 7 days.

## 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

<ParamField query="lat" type="float" required>
  Latitude of the location.
</ParamField>

<ParamField query="lng" type="float" required>
  Longitude of the location.
</ParamField>

<ParamField query="days" type="integer">
  Number of days to return. Must be between 1 and 7. Defaults to `3`.
</ParamField>

<ParamField query="sport" type="string">
  Activity type used to weight the per-hour playability scores. Defaults to `outdoor`. See [supported sports](/supported-sports).
</ParamField>

## Example request

<CodeGroup>
  ```bash cURL theme={null}
  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'
  ```

  ```javascript Node.js theme={null}
  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();
  ```

  ```python Python theme={null}
  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']}
  )
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "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

<ResponseField name="location" type="object">
  The coordinates used for the forecast.
</ResponseField>

<ResponseField name="hours" type="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)
</ResponseField>

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