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

# Current Weather API

> Get current weather conditions for a coordinate, powered by Apple WeatherKit

## Overview

Returns the current weather for a latitude/longitude pair. The server fetches Apple WeatherKit's `currentWeather` data set and converts it to **imperial units** — this contract powers the live weather UI (`useWeather` / `CityWeatherBanner`) and is also written (converted to metric) onto `helloapp_routehistory` rows by the same function's webhook path.

Responses are cached for **10 minutes** (`Cache-Control: public, max-age=600`); calling more often returns the same data.

## Authentication

Any authenticated caller (user session, publishable key, or service key):

```
Authorization: Bearer YOUR_API_KEY
```

## Query Parameters

<ParamField query="latitude" type="number" required>
  Latitude in decimal degrees, `-90` to `90`. `lat` is accepted as an alias.
</ParamField>

<ParamField query="longitude" type="number" required>
  Longitude in decimal degrees, `-180` to `180`. `lon` is accepted as an alias.
</ParamField>

## Response

<ResponseField name="temperature" type="number">
  Current temperature in **degrees Fahrenheit**, rounded to one decimal. (WeatherKit returns Celsius; the server converts. Clients converting for metric riders must treat °F as the source unit.)
</ResponseField>

<ResponseField name="feels_like" type="number">
  Apparent temperature in **degrees Fahrenheit**, rounded to one decimal.
</ResponseField>

<ResponseField name="conditions" type="string[]">
  WeatherKit condition codes. `conditions[0]` is the primary condition — one of WeatherKit's `conditionCode` values (`Clear`, `MostlyClear`, `PartlyCloudy`, `Cloudy`, `Drizzle`, `Rain`, `HeavyRain`, `Thunderstorms`, `Snow`, `Foggy`, …). The server may append temperature modifiers after it: `Cold` (below 40 °F) or `Hot` (above 85 °F).

  Map codes to display strings with `getHumanReadableWeather` in `packages/shared/lib/weatherText.ts` — don't show the raw code.
</ResponseField>

<ResponseField name="wind_speed" type="number">
  Wind speed in **miles per hour**, rounded to one decimal.
</ResponseField>

<ResponseField name="wind_direction" type="number | null">
  Direction the wind is blowing from, in degrees `[0, 360)` (0 = north), or `null` when WeatherKit omits it.
</ResponseField>

<ResponseField name="humidity" type="number">
  Relative humidity as an integer percentage, `0`–`100`.
</ResponseField>

## Example

```bash theme={null}
curl 'https://YOUR_PROJECT.supabase.co/functions/v1/weather?latitude=51.5074&longitude=-0.1276' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```json theme={null}
{
  "temperature": 52.8,
  "feels_like": 49.4,
  "conditions": ["MostlyClear"],
  "wind_speed": 5.4,
  "wind_direction": 252,
  "humidity": 79
}
```

A real response is committed as the fixture `packages/shared/__fixtures__/weather-london.json` — reuse it in tests instead of hand-crafting the shape.

## Errors

| Status | Meaning                                          |
| ------ | ------------------------------------------------ |
| `400`  | Missing or invalid `latitude` / `longitude`.     |
| `401`  | Missing or invalid credentials.                  |
| `503`  | WeatherKit secrets not configured on the server. |
| `500`  | WeatherKit upstream failure.                     |