Developers
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"
  }
  warnings?: {
    id: string
    title: string
    level: "none" | "advice" | "watch_and_act" | "emergency_warning"
    areas?: string
    action?: string
    description?: string
    agency: string
    issued?: number
    updated: number
    url?: string
    credit: {
      name: string
      attribution: string
      url?: string
    }
  }[]
  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/weather/radar

The rain radar's recent frames (the past two hours, every 10 minutes, oldest first) as tile addresses for a map's raster layer, to maxZoom, with the credit to show. enabled is false and there are no frames while the radar is off. Counts as one request.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
weather:read
Get an API key 
curl 'https://api.cactive.com.au/v1/weather/radar' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  enabled: boolean
  maxZoom: number
  frames: {
    time: number
    tiles: string
  }[]
  source: {
    id: string
    name: string
    attribution: string
    url: 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
}
GET/v1/me/weather/alerts

Your rain and severe weather alerts (docs/weather/alerts.md): the kinds, the places (saved place ids and here) and their limits.

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/alerts' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  rain: boolean
  warnings: boolean
  places: string[]
  hereAt?: number
  updatedAt?: number
  limits: {
    places: number
    hereHours: number
    rainLeadMinutes: number
  }
}
PUT/v1/me/weather/alerts

Turns rain and severe weather alerts on or off and chooses their places (saved ones and here, My Location, up to weather.alerts.places). Push only. Dropping here forgets My Location. 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

  • rainbooleanrequired
  • warningsbooleanrequired
  • placesstring[]required

    Up to 100 items. Each 1–64 characters.

Errors

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

Response 200

{
  rain: boolean
  warnings: boolean
  places: string[]
  hereAt?: number
  updatedAt?: number
  limits: {
    places: number
    hereHours: number
    rainLeadMinutes: number
  }
}
PUT/v1/me/weather/alerts/here

Where this phone or browser is, while My Location is one of your alert places: kept as its 1 km cell for weather.alerts.hereHours, never logged. 403 unless My Location alerts are on. 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

  • latnumberrequired

    -90–90.

  • lonnumberrequired

    -180–180.

Errors

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

Response 200

{
  hereAt: number
}
DELETE/v1/me/weather/alerts/here

Forgets My Location's last cell.

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

Errors

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

Response 204 with no body