Current Weather API

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

GET /weather/

Current Weather API

cURL

curl --request GET \
  --url https://api.example.com/weather/

200

{
  "temperature": 123,
  "feels_like": 123,
  "conditions": [
    "<string>"
  ],
  "wind_speed": 123,
  "wind_direction": {},
  "humidity": 123
}

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

latitude · number · required

Latitude in decimal degrees, -90 to 90. lat is accepted as an alias.

longitude · number · required

Longitude in decimal degrees, -180 to 180. lon is accepted as an alias.

Response

temperature · 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.)

feels_like · number

Apparent temperature in degrees Fahrenheit, rounded to one decimal.

conditions · 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.

wind_speed · number

Wind speed in miles per hour, rounded to one decimal.

wind_direction · number | null

Direction the wind is blowing from, in degrees [0, 360) (0 = north), or null when WeatherKit omits it.

humidity · number

Relative humidity as an integer percentage, 0–100.

Example

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

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