Vaisala Xweather API & Maps

View saved version →

---
name: mapsgl
description: This skill should be used when working with the Xweather MapsGL JavaScript SDK for the web (@xweather/mapsgl) — setting up a MapsGL map controller for Mapbox GL, MapLibre GL, Google Maps, or Leaflet, and adding, removing, styling, filtering, masking, or animating MapsGL weather layers and custom data layers. Use it whenever a task mentions MapsGL, aerisweather.mapsgl, addWeatherLayer, weather map layers, or client-side WebGL weather rendering. Also use it for questions about how MapsGL usage or cost is measured — sessions, the 5-minute clock intervals, the 150x access multiplier, or how many accesses a MapsGL map consumes. Also covers Xweather's attribution requirement — the 'Powered by Vaisala Xweather' credit and logo rules that apply wherever Xweather data or imagery is displayed.
license: MIT
---

# MapsGL JavaScript SDK

The MapsGL JavaScript SDK (`@xweather/mapsgl`) renders weather and custom map data client-side in
WebGL, layered on top of Mapbox GL, MapLibre GL, Google Maps, or Leaflet. It requires an active
Xweather account with Weather API + Maps access (client id + secret).

**This skill is the web-based JavaScript SDK.** For a native Swift app on iOS, iPadOS, Mac Catalyst, or visionOS, use
the `mapsgl-apple` skill instead — a separate SDK with a Swift API (`MapboxMapController`,
`WeatherService.LayerCode`), its own install channels, and a smaller layer set. The concepts below
transfer; none of the code does. MapsGL ships for Android as well.

**Always qualify the name as the *MapsGL* JavaScript SDK.** Xweather ships an unrelated product simply
called the JavaScript SDK (<https://www.xweather.com/docs/javascript-sdk>), so the bare term is
ambiguous. Xweather's own naming for the family is MapsGL, MapsGL iOS, and MapsGL Android; "MapsGL
JavaScript SDK" is the unambiguous way to name this one.

## How to write MapsGL code examples

**Default to a single self-contained HTML file using vanilla JavaScript and the CDN build.** One
file the user can save and open in a browser — CDN `<script>`/`<link>` tags, a `<div>` for the map,
and a plain `<script>` block. No build step, no bundler, no package installs, no framework.

In that form, MapsGL lives on the global `aerisweather.mapsgl` namespace:

```javascript
const account = new aerisweather.mapsgl.Account('CLIENT_ID', 'CLIENT_SECRET');
const controller = new aerisweather.mapsgl.MapboxMapController(map, { account });
```

**Look up the current released version before writing any example.** Don't reuse a version from
memory or from an earlier turn — MapsGL ships often, and a stale pin is the most common thing to go
wrong in otherwise-correct example code:

```bash
curl -s https://www.xweather.com/docs/api/releases/versions \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["products"]["mapsgl"]["version"])'
```

That endpoint is the release source of truth for every Xweather product, keyed by product id —
`mapsgl` here, alongside `weather-api`, `maps`, `maps-ui-sdk`, `mapsgl-apple-sdk`,
`mapsgl-android-sdk`, `mcp-server`, `phrases-api`. It's a small public JSON document, no auth needed.

**MapsGL's own script and stylesheet always come from `cdn.aerisapi.com`**, with that version
substituted:

```html
<link href="https://cdn.aerisapi.com/sdk/js/mapsgl/1.9.4/aerisweather.mapsgl.css" rel="stylesheet" />
<script defer src="https://cdn.aerisapi.com/sdk/js/mapsgl/1.9.4/aerisweather.mapsgl.js"></script>
```

`1.9.4` above is the version at the time this file was last regenerated — use it only as a fallback
if the endpoint can't be reached, and say so when you do.

Note that **npm may be ahead of the released version.** `@xweather/mapsgl` on npm has carried a
higher version than the releases endpoint reports, and `cdn.aerisapi.com` serves those newer paths
too — so a version that resolves is not evidence it's the current release. Trust the releases
endpoint, not npm and not a 200 from the CDN.

Never substitute `unpkg.com`, `cdn.jsdelivr.net

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 9 — file references are metadata, not package contents.

View saved version →

---
name: mapsgl-android
description: >-
  This skill should be used when working with the Xweather MapsGL Android SDK
  (mapsgl-android-sdk / com.xweather.mapsgl) - setting up MapboxMapController,
  adding or removing weather layers via LayerCode or WeatherService configs,
  styling with StyleValue and Expression, custom sources and layers, legends,
  data inspector presentations, timeline animation, layer masks, or integrating
  the AAR/JitPack dependency into an Android app. Use it whenever a task mentions
  MapsGL Android, MapboxMapController, addWeatherLayer, LayerCode,
  WeatherService, XweatherAccount, or weather overlays on Mapbox Maps SDK for
  Android. Also covers MapsGL session-based usage/cost (shared with the JS SDK)
  and common Android gotchas (Mercator, OpenGL ES 3.0, minSdk 28, Mapbox peer
  dependency). Documents the MapsGL Android 1.6.1 release - every API here is in
  that published build, with no unreleased or development-branch surface. When docs
  and SDK disagree, prefer the SDK (source / KDoc / demos) over xweather.com
  documentation.
license: MIT
---

# MapsGL Android

MapsGL Android renders weather and custom map data on top of the **Mapbox Maps
SDK for Android** (encoded grids via OpenGL ES custom layers; many vector
weather layers via Mapbox style layers). Requires an Xweather account (Weather
API + Maps) **and** Mapbox access / downloads tokens.

## Source of truth (read this first)

When answering or writing code, resolve conflicts in this order:

1. **The MapsGL Android SDK** - public Kotlin APIs in `mapsglmaps` / published AAR,
   in-repo demos under `app/`, and generated KDoc
2. **This skill** (kept to match the SDK)
3. **https://www.xweather.com/docs/mapsgl-android-sdk/** - useful for tutorials and
   recipes, but often lagging (deprecated ctors, wrong `removeWeatherLayer` args,
   missing Mapbox peer dep, "coming soon" for shipped features, invented overload
   shapes)

**Prefer the SDK to the docs.** If a docs snippet disagrees with a real method
signature, package, or demo in the SDK, follow the SDK and say so. Never invent an
API - if it isn't in the SDK source, KDoc or a demo, it doesn't exist.

Docs hub (optional context only):
https://www.xweather.com/docs/mapsgl-android-sdk/

**API scope:** public MapsGL Android APIs only - no internals.

**This skill documents the 1.6.1 release.** Every API described here exists in the
published 1.6.1 artifact - there is no unreleased or development-branch surface to
filter out, and nothing is marked *(unreleased)*.

That also bounds what the skill can offer. Features added after 1.6.1 - the
`["map-time"]` filter expression, MapsGL's own GLES vector rendering pipeline, and
the `*-text` data-query layers - are deliberately absent. If a task needs one of
those, say it is not available in 1.6.1 rather than writing code against it.

**Never hardcode a version number.** Resolve the current release when you need
one:

```bash
curl -s https://www.xweather.com/docs/api/releases/versions \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["products"]["mapsgl-android-sdk"]["version"])'
```

That endpoint is the release source of truth for every Xweather product, keyed by
product id - `mapsgl-android-sdk` here, alongside `mapsgl`, `mapsgl-apple-sdk`,
`weather-api`, `maps`, and others. It's a small public JSON document, no auth
needed.

A version is only needed for a deliberate Gradle pin or an API-reference URL.
Where this skill's `references/` note behaviour "on 1.6.x", that records what the
guidance was checked against - verify against the release you're actually on
before relying on it.

## How to write examples

**Default:** one Kotlin `Activity` / Fragment with ViewBinding + Mapbox `MapView`.
No Compose unless asked. Match the surrounding project when it disagrees with that
default - if it is a Fragment codebase, or already uses Compose interop, follow it.

## API reference

`references/api-reference.md` carries real signatures for every public 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 14 — file references are metadata, not package contents.

View saved version →

---
name: mapsgl-apple
description: This skill should be used when working with the Xweather MapsGL SDK for Apple platforms (the MapsGL iOS/iPadOS/macCatalyst/visionOS SDK) — installing it via Swift Package Manager, CocoaPods, Carthage or xcframeworks, creating a MapboxMapController or MapLibreMapController, and adding, removing, styling, animating or inspecting MapsGL weather layers in Swift. Use it whenever a task mentions MapsGL on iOS or Apple platforms, mapsgl-apple-sdk, MapsGLMaps, MapsGLMapbox, MapsGLMapLibre, XweatherAccount, WeatherService.LayerCode, addWeatherLayer in Swift, or a native weather map in SwiftUI or UIKit. Also use it for questions about MapsGL session usage or cost in an Apple app — sessions, the 5-minute clock intervals, the access multiplier, and which view and app lifecycle events should attach and detach weather layers. Also covers Xweather's attribution requirement — the 'Powered by Vaisala Xweather' credit and logo rules that apply wherever Xweather data or imagery is displayed.
license: MIT
---

# MapsGL for Apple platforms

The Xweather MapsGL SDK for Apple platforms renders weather and custom map data client-side with
Metal, layered on top of **Mapbox Maps** or **MapLibre Native**. It requires an active Xweather
account with Weather API + Maps access (client id + secret).

Platform support comes from the package manifest: **iOS 16+, macCatalyst 16+, visionOS 1+**. There is
no native macOS (AppKit) target — a "macOS" app here means Mac Catalyst.

Docs: https://www.xweather.com/docs/mapsgl-apple-sdk/getting-started ·
Distribution + demo app: https://github.com/vaisala-xweather/mapsgl-apple-sdk

## Ask which map provider unless the context tells you

The map provider is not a stylistic preference that can be defaulted: Mapbox and MapLibre resolve
*different Swift Package branches*, different transitive SDKs, and different map-view types. Getting
it wrong means the code doesn't compile and the package graph has to be redone.

So **infer it when the context actually says, and ask when it doesn't.** Never pick one by default.

**Infer it** from evidence like:

- the user named the provider in their request;
- the project already integrates one — an `import MapsGLMapbox` / `import MapsGLMapLibre`, a resolved
  `mapbox-maps-ios` or `maplibre-gl-native-distribution` dependency, a `Podfile` naming one, an
  `MLNMapView` or `MapboxMaps.MapView` in the source, or a `MBXAccessToken` in an Info.plist;
- the project already uses the provider's SDK elsewhere, even without MapsGL — a Mapbox-based map
  screen means Mapbox.

When you infer, **say which provider you picked and what told you**, so a wrong read is cheap to
correct.

**Ask** when the evidence is absent or contradictory — a greenfield app, a project with no map
dependency yet, or one carrying traces of both. Weak circumstantial signals ("we want a dark map
style", "our designer sent Mapbox screenshots") are not evidence of an integration; ask rather than
build the whole package graph on them.

Trade-offs to offer alongside the question, briefly:

| | Mapbox Maps | MapLibre Native |
|---|---|---|
| Basemap key | Mapbox account access token required, plus a secret token to download the SDK | None — but the style URL's tile provider may need one (CARTO's public styles don't) |
| Cost | Mapbox map-load pricing applies | No basemap vendor cost |
| SwiftUI | Native `Map` view | `MLNMapView` wrapped in a `UIViewRepresentable` |
| MapsGL constraint | Must set the **mercator** projection — the default globe projection is incompatible | None |

## How to write MapsGL Apple examples

**Default to SwiftUI.** Produce UIKit only when the project is UIKit (a `UIViewController`-based app,
storyboards/XIBs, an `AppDelegate`/`SceneDelegate` pair with no SwiftUI `App`) or the user asks for
it. Match the surrounding project over the default whenever the two disagree — including Swift
concurrency style, view-model conventions, and how the app already stores secrets.

**N

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 8 — file references are metadata, not package contents.

View saved version →

---
name: raster-maps
description: This skill should be used to build Xweather Raster Maps image URLs (maps.api.xweather.com) — either static map images or XYZ map tile URLs for Leaflet, Mapbox, Google Maps, OpenLayers and similar libraries — from a description of the weather imagery wanted. Use it whenever a task mentions Raster Maps, maps.api.xweather.com, maps.aerisapi.com, an Xweather weather map layer or overlay (radar, satellite, alerts, temperatures, lightning, tropical cyclones, air quality, base maps, admin overlays), a weather map image or tile layer, layer opacity/blur/blend/scale-hsla modifiers, or asks how Raster Maps usage is measured — map units, tile counts, the daily allowance, or how many accesses a static map or tile layer will consume. Also covers Xweather's attribution requirement — the 'Powered by Vaisala Xweather' credit and logo rules that apply wherever Xweather data or imagery is displayed.
compatibility: Skill instructions are provider-neutral. The bundled scripts/xwmap.py needs Python 3 (standard library only) and network access to maps.api.xweather.com.
license: MIT
---

# Xweather Raster Maps URL builder

Turn a description of wanted weather imagery into a `maps.api.xweather.com` URL — as a standalone
static image or as a tile template for an interactive mapping library.

This is a different product from the Weather API: different host, different URL grammar, and
credentials sit **in the path**, not in the query string.

```
https://maps.api.xweather.com/{client_id}_{client_secret}/{layers}/…/{offset}.{format}
```

## Two output methods — ask which one

Every Raster Maps request is one of two shapes, and they are not interchangeable:

| | Static map | Map tiles |
|---|---|---|
| Produces | A single finished image | A 256×256 tile template a library fetches many of |
| Use when | Email, report, dashboard panel, `<img>` tag, Slack, PDF | Leaflet / Mapbox / Google Maps / OpenLayers / Apple Maps |
| Path | `{layers}/{w}x{h}/{place},{zoom}/{offset}.{fmt}` | `{layers}/{z}/{x}/{y}/{offset}.{fmt}` |
| Interactive | No — no pan or zoom | Yes |

**If the user hasn't said which one they want, ask before generating anything.** Use
Ask a direct either/or question — a structured-choice prompt if the agent has one, plain text otherwise.
Don't guess from weak signals and don't produce both by default — a tile template pasted into an
`<img>` tag renders one 256-pixel square, and a static URL handed to Leaflet fails outright.

Signals strong enough to skip the question: the user names a mapping library, says "tile layer" or
"XYZ", or gives `{z}/{x}/{y}` (→ tiles); or names pixel dimensions, says "image", "PNG for a
report", or shows an `<img>` tag (→ static).

## Workflow

1. **Determine the output method** — ask if not already clear (above).
2. **Pick the layers.** Use the intent map below and confirm codes against `references/layers.md`.
   Order matters: they composite left to right, so base map first, weather next, labels last.
3. **Add the geography.** Static: `place,zoom` or a `south,west,north,east` bounding box. Tiles: the
   library substitutes `{z}/{x}/{y}` — leave the placeholders in.
4. **Add the time offset.** `current` unless the user wants past or forecast imagery.
5. **Pick the format.** `png` for tile overlays (transparency is mandatory); `png` or `jpg` for
   static maps that include their own base layer.
6. **Apply modifiers** if the request implies them — opacity, blur, blend, recolour. See
   `references/modifiers.md`.
7. **Report the URL with its map-unit cost** (see Map units), then handle credentials (see below).
8. **Include the attribution.** Any markup you hand over — an `<img>` tag, a tile layer, a template —
   needs the Xweather credit alongside it. See "Attribution is required" below.

Never invent a layer code. Check `references/layers.md`, or refetch the live catalog:

```bash
curl -s https://www.xweather.com/docs/api/maps/layers
```

That JSON (`{ layers: [{ id, title, description,

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.

View saved version →

---
name: weather-api
description: Build and run Xweather Weather API request URLs for data.api.xweather.com from plain-language requirements. Use when a task mentions the Xweather or legacy Aeris API, weather endpoints such as observations, conditions, forecasts, alerts, lightning, air quality, tropical cyclones, tides, or road weather; asks for an API URL or query; needs help debugging an empty or failed request; asks about access costs, endpoint multipliers, rate limits, or allowance usage; or needs guidance for the hosted Xweather MCP server at mcp.api.xweather.com, including availability, connection, authentication, and tool scoping. Also covers Xweather's attribution requirement — the 'Powered by Vaisala Xweather' credit and logo rules that apply wherever Xweather data or imagery is displayed.
compatibility: Skill instructions are provider-neutral. The bundled scripts/xwrequest.py needs Python 3 (standard library only) and network access to data.api.xweather.com.
license: MIT
---

# Xweather Weather API URL builder

Turn a description of wanted weather data into a correct `data.api.xweather.com` URL — and, when
credentials are available, execute it and return the data alongside the URL.

## Request anatomy

```
https://data.api.xweather.com/{endpoint}/{action}/{:id}?{params}&client_id=…&client_secret=…
```

| Segment | Example | Notes |
|---|---|---|
| endpoint | `observations`, `conditions/summary` | *What* data. 59 of them — see `references/endpoints.md`. |
| action | `closest`, `within`, `search`, `route`, `contains`, `affects` | *How* to look it up. Omitted entirely for `:id` and `:all`. |
| `:id` | `seattle,wa`, `98109`, `44.97,-93.26`, `KMSP` | The place or record identifier. Goes in `p=` instead when an action occupies the path slot. |
| params | `filter=`, `query=`, `fields=`, `limit=`, `from=`/`to=`, `format=` | Shape the result. |
| credentials | `client_id` + `client_secret` | Query params on every request; no header form exists. |

`api.aerisapi.com` is the legacy host and still works — always emit `data.api.xweather.com`.

## Workflow

1. **Extract from the prompt:** what data, which place(s), what time, and what shape of answer
   (one record, N nearest, everything in an area, along a route, is-this-point-inside-a-polygon).
2. **Pick the endpoint.** Use the intent map below; confirm against `references/endpoints.md`.
3. **Pick the action** from the decision table below. Verify the endpoint actually supports it —
   `endpoints.md` lists supported actions per endpoint, and an unsupported one returns
   `not_implemented`.
4. **Add parameters.** `filter` and `query` tokens are endpoint-specific; only use tokens listed for
   that endpoint in `endpoints.md`. Read `references/filters.md` when choosing between similar
   tokens (`standard` vs `all` for alerts, `day` vs `daynight` vs `mdnt2mdnt` for forecasts) — grep
   for the `## /endpoint` heading rather than reading the whole file.
5. **Sanity-check against a documented example.** `references/examples.md` has the API's own example
   requests for every endpoint; `references/recipes.md` has 34 real-world queries by use case. If
   the request resembles one, copy its structure instead of inventing parameters.
6. **Emit the URL with its access cost** (see Access cost — always report it), then decide whether to
   run it (see Executing the request).

Never invent an endpoint, action, filter token, or query property. If unsure whether one exists,
check `endpoints.md`, or refetch the live catalog:

```bash
curl -s https://www.xweather.com/docs/api/weather-api/endpoints
```

That JSON (`{ endpoint: {...}, action: {...} }`) is the authoritative, always-current list of every
endpoint with its supported actions, params, filters, query properties, and sort fields — it is what
`references/endpoints.md` was generated from. Use it when a user asks about something the reference
doesn't cover, or when a request fails with `invalid_request` / `not_implemented`.

## Intent → end

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 7 — file references are metadata, not package contents.

View saved version →

---
name: webhooks
description: This skill should be used to design, build, secure, or debug an Xweather Webhooks receiver — the push alternative to polling the Weather API. Use it whenever a task mentions Xweather webhooks, pushed weather data, a weather webhook receiver or endpoint, subscribing to pushed hail/lightning/alerts/storm-cell data, or asks how to stop polling the Xweather API and receive data in real time instead. Also use it when writing the endpoint handler, choosing a data set to subscribe to, or preparing the registration details Xweather needs. Also covers Xweather's attribution requirement — the 'Powered by Vaisala Xweather' credit and logo rules that apply wherever Xweather data or imagery is displayed.
license: MIT
---

# Xweather Webhooks

Xweather pushes data sets to an HTTPS endpoint you own, instead of your application polling
`data.api.xweather.com` on a timer. The payload is **byte-for-byte the same shape the Weather API
returns**, so existing response-parsing code is reusable with almost no change.

**Webhooks are a premium add-on requiring a separate subscription, and endpoints are registered by
Xweather staff — not self-service.** There is no API call or dashboard toggle that turns this on. Say
so early: the work splits into what the user can build today (the receiver) and what needs a
conversation with their account executive (the subscription and registration).

## When webhooks are the right answer

Reach for them when the user is polling frequently for data that changes unpredictably — lightning
strikes, hail threats, new alerts, storm cell updates. Polling that on a short interval burns
accesses continuously and still adds latency; push removes both problems.

Polling via the `weather-api` skill stays the better fit when the data is requested on
demand (a user opens a page), when the update cadence is slow and predictable (daily normals, hourly
temperatures), or when the user can't host a public HTTPS endpoint.

## How a delivery works

Xweather sends an HTTP `POST` to the registered URL.

| | |
|---|---|
| Method | `POST` |
| `Content-Type` | `application/json` |
| `x-api-key` | A client-generated shared secret, proving the delivery came from Xweather. May be a query parameter instead of a header, if preferred. |
| Body | The standard Xweather API response envelope — JSON or GeoJSON, whichever was configured |

The endpoint must answer with a **2xx** status — `202` is the conventional choice — and do it
*immediately*. The response body is ignored.

**Acknowledge first, process second.** Any real work belongs in a background job, queue, or thread
started after the status is written. A handler that parses, matches polygons, and sends notifications
before responding will eventually exceed the delivery timeout, and a timeout is treated as a failed
delivery.

### Retries

A non-2xx status or a connection timeout triggers a retry, **typically no more than two or three
attempts**. After that the delivery is marked failed and is not attempted again — the next
opportunity is the next update for that data set. There is no replay or backfill mechanism, so a
receiver that's down during an event has permanently missed it. Two consequences worth raising:

- Deliveries are effectively at-most-once after retries are exhausted. If gapless history matters,
  pair the webhook with a periodic API query as a reconciliation backstop.
- Handlers should be **idempotent**, because a retry can duplicate a delivery your server actually
  did process but was too slow to acknowledge. Key writes on a stable field — station id, alert id,
  strike timestamp — and upsert rather than insert.

## Available data sets

Common:

| Data set | What arrives |
|---|---|
| Hail Threats | Real-time hail threat polygons with severity ratings |
| Lightning Threats | Predictive lightning threat zones |
| Lightning | Individual strike events as they occur |
| Lightning Analytics | Strike events with enhanced analytical data |
| Lightning 

Preview of the first 4,000 characters. Read full instructions →