Docs
Developer Portal

API reference

Weather

Forecasts, air quality and place search, and your saved places and units.
Read the Guide
GET/v1/weather/forecast

The forecast at a point: current conditions, today, hours hourly (1–48, default 24, from the current hour) and days daily (1–16, default 10, from today in the place's time zone), air quality where there is some, and the attribution to show with it. Cached for 10 minutes per 1 km cell. units (metric or imperial) defaults to the person's saved choice. place names the caller's saved place within 1.5 km. 429 (with Retry-After) past the per-person limits.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
weather:read
Get an API key

Query parameters

  • latnumberrequired

    -90–90. Coerced from a string.

  • lonnumberrequired

    -180–180. Coerced from a string.

  • units"metric" | "imperial"
  • daysinteger

    1–16. Coerced from a string.

  • hoursinteger

    1–48. Coerced from a string.

Errors

  • 400Give lat and lon.
curl 'https://api.cactive.com.au/v1/weather/forecast?lat=1&lon=1' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  at: number
  timeZone: string
  units: {
    temperature: "C" | "F"
    wind: "km/h" | "mph"
    precipitation: "in" | "mm"
  }
  place?: {
    name: string
    region?: string
    country?: string
  }
  current: {
    temp: number
    feelsLike: number
    humidity: number
    windSpeed: number
    windGust?: number
    windDir: number
    windCompass: string
    pressure?: number
    uv?: number
    precip: number
    cloud: number
    visibility?: number
    isDay: boolean
    code: number
    condition: string
    symbol: string
    icon: "cloud" | "sunny" | "bedtime" | "partly-cloudy-day" | "partly-cloudy-night" | "foggy" | "rainy-light" | "rainy" | "rainy-heavy" | "weather-mix" | "weather-snowy" | "snowing-heavy" | "grain" | "thunderstorm"
  }
  today: {
    high: number
    low: number
    precipChance: number
    precipSum: number
    sunrise: number
    sunset: number
    uvMax?: number
    windMax?: number
  }
  hourly: {
    at: number
    temp: number
    precipChance: number
    precip: number
    code: number
    symbol: string
    icon: "cloud" | "sunny" | "bedtime" | "partly-cloudy-day" | "partly-cloudy-night" | "foggy" | "rainy-light" | "rainy" | "rainy-heavy" | "weather-mix" | "weather-snowy" | "snowing-heavy" | "grain" | "thunderstorm"
    windSpeed: number
    isDay: boolean
  }[]
  daily: {
    date: string
    high: number
    low: number
    precipChance: number
    precipSum: number
    code: number
    condition: string
    symbol: string
    icon: "cloud" | "sunny" | "bedtime" | "partly-cloudy-day" | "partly-cloudy-night" | "foggy" | "rainy-light" | "rainy" | "rainy-heavy" | "weather-mix" | "weather-snowy" | "snowing-heavy" | "grain" | "thunderstorm"
    sunrise: number
    sunset: number
    windMax: number
    uvMax?: number
  }[]
  airQuality?: {
    aqi: number
    pm25?: number
    category: "Good" | "Fair" | "Moderate" | "Poor" | "Very poor" | "Extremely poor"
  }
  source: {
    id: string
    name: string
    attribution: string
    url: string
  }
}
GET/v1/weather/places/search

Places by name or postcode, best first (count 1–10, default 5); "Name, region or country" narrows. Each has a placeId (gn: and its GeoNames id) to save it with. Fewer than 2 characters find nothing.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
weather:read
Get an API key

Query parameters

  • qstringrequired

    Up to 100 characters.

  • countinteger

    1–10. Coerced from a string.

curl 'https://api.cactive.com.au/v1/weather/places/search?q=example' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  results: {
    placeId: string
    name: string
    region?: string
    country?: string
    lat: number
    lon: number
    timeZone?: string
  }[]
}
GET/v1/me/weather/places

Your saved places in your order, and your units (metric until you choose). The same on every device.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
weather:read
Get an API key

Errors

  • 403Saved places belong to people, not keys.
curl 'https://api.cactive.com.au/v1/me/weather/places' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  places: {
    placeId: string
    name: string
    region?: string
    country?: string
    lat: number
    lon: number
    timeZone: string
  }[]
  units: "metric" | "imperial"
  updatedAt?: number
}
PUT/v1/me/weather/places

Replaces your saved places with places, in order (up to the weather.places limit, 20 by default), and sets units when given. A place without a placeId gets one (wpl_…). Coordinates are kept to 3 decimals. Not from an assistant.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
weather:write
Get an API key

Request body

  • placesobject[]required

    Up to 100 items.

  • places[].placeIdstring

    Matches ^[A-Za-z0-9:_.-]{1,64}$.

  • places[].namestringrequired

    1–100 characters. Trimmed.

  • places[].regionstring

    Up to 100 characters. Trimmed.

  • places[].countrystring

    Up to 100 characters. Trimmed.

  • places[].latnumberrequired

    -90–90.

  • places[].lonnumberrequired

    -180–180.

  • places[].timeZonestringrequired

    1–64 characters.

  • units"metric" | "imperial"

Errors

  • 403Saved places belong to people, not keys.
  • 403Change your places in the Weather app.
curl -X PUT 'https://api.cactive.com.au/v1/me/weather/places' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "places": [
      {
        "name": "Example",
        "lat": 1,
        "lon": 1,
        "timeZone": "example"
      }
    ]
  }'
Send it from this page with your session or a key.

Response 200

{
  places: {
    placeId: string
    name: string
    region?: string
    country?: string
    lat: number
    lon: number
    timeZone: string
  }[]
  units: "metric" | "imperial"
  updatedAt?: number
}